Nd4js NPM | npm.io

Introduction

nd4js is a lightweight JavaScript library for ND-Arrays including some optimization functionality and one of the most complete linear algebra modules for the web. It is strongly inspired by NumPy. There are, however, some key differences. Broadcasting, slicing and reshape work in a similar way as in NumPy. Instead of the predefined operations (+, -, *, /, sin, cos, ...), nd4js relies on functional-style map- and zip-like methods.

The goal of this library is to explore and improve the author's understanding of linear algebra, optimization and computational numerics in general. The author is therefore constantly working on the edge of his knowledge. Despite his best efforts, no guarantees can be made about performance, numeric accuracy, reproducability or anything at all. There will be bugs, underflows, overflows, NaNs, memory issues and the like. If You find a bug - and don't want to keep it - feel free file an issue or a PR.

A function reference can be found here.

Installation

npm i nd4js

Building and Testing

nd4js is built and tested using NPM. To initialize the project open the command line, navigate to the project directory and call:

npm i

To cover as many test cases as possible with little effort, nd4js mostly uses randomized testing instead of hand crafted test cases. As a result, testing the entire project takes rather long (~50 minutes). If You want to run only a subset of the tests during development, change the glob pattern of the file setting inside of karma.conf.js, e.g. use 'src/la/**/*_test.js' instead of 'src/**/*_test.js' to test linear algebra methods only.

In order to run the tests call:

npm run test

To build/bundle the library, call:

npm run build

nd4js has some development dependencies, most notably Babel and Webpack for bundling and Jasmine for testing. There are however no deployment dependencies as of yet.

Array Instantiation

nd.array allows to create NDArray instances in a well-readable and intuitive way, using nested JavaScript Arrays.

const nd = require('nd4js')

const a = nd.array([
  [1,0,0],
  [0,2,0],
  [0,0,3]
])

An NDArray can also be created from its entries' indices using nd.tabulate.

Input:

const a = nd.tabulate([1000,1000], (i,j) => i==j ? 1 : 0 )
console.log( a.toString() )

Output:

[[ 1,  0,  0,  0,  0,  ...990 more...,  0,  0,  0,  0,  0],
 [ 0,  1,  0,  0,  0,  ...990 more...,  0,  0,  0,  0,  0],
 [ 0,  0,  1,  0,  0,  ...990 more...,  0,  0,  0,  0,  0],
 [ 0,  0,  0,  1,  0,  ...990 more...,  0,  0,  0,  0,  0],
 [ 0,  0,  0,  0,  1,  ...990 more...,  0,  0,  0,  0,  0],
  ...990 more...,
 [ 0,  0,  0,  0,  0,  ...990 more...,  1,  0,  0,  0,  0],
 [ 0,  0,  0,  0,  0,  ...990 more...,  0,  1,  0,  0,  0],
 [ 0,  0,  0,  0,  0,  ...990 more...,  0,  0,  1,  0,  0],
 [ 0,  0,  0,  0,  0,  ...990 more...,  0,  0,  0,  1,  0],
 [ 0,  0,  0,  0,  0,  ...990 more...,  0,  0,  0,  0,  1]]

Random Access

Since nd.Array extends Function, elements can be read by calling the array object.

Input:

const a = nd.array([
  [1,2],
  [3,4]
])

console.log( a(0,0) )
console.log( a(0,1) )
console.log( a(1,0) )
console.log( a(1,1) )

Output:

nd.NDArray.set allows writing array entries.

Input:

const a = nd.tabulate([3,3], () => 0 )

for( let i=3; i-- > 0; )
for( let j=3; j-- > 0; )
  a.set( [i,j], 10*(i+1)+(j+1) );

console.log( a.toString() );

Output:

[[ 11, 12, 13 ],
 [ 21, 22, 23 ],
 [ 31, 32, 33 ]]

If array elements are to be modified, nd.NDArray.modify is a concise alternative to using nd.NDArray.get and nd.NDArray.set.

Input:

const a = nd.array([[1, 2, 3],
                    [4, 5, 6]])

a.modify([0,1], x => 7*x)

console.log( a.toString() );

Output:

[[  1, 14,  3 ],
 [  4,  5,  6 ]]

Unary Operations (sin, cos, exp, ...)

nd.NDArray.mapElems is used to apply unary operations on an NDArray.

Input:

const a = nd.array([
  [1,2],
  [3,4]
])

const b = a.mapElems( (a_ij, i,j) => i==j ? a_ij : a_ij*a_ij )
console.log( b.toString() )

Output:

[[         1,          4],
 [         9,          4]]

Binary Operations (+, -, *, /, ...)

nd.zip_elems can be used to apply binary operations on two NDArrays.

Input:

const
  a = nd.array([
    [11,12,13],
    [21,22,23],
    [31,32,33]
  ]),
  b = nd.array([
    [1,2,3],
    [4,5,6],
    [7,8,9]
  ])

const c = nd.zip_elems([a,b], (a_ij,b_ij, i,j) => i==j ? a_ij : b_ij )
console.log( c.toString() )

Output:

[[        11,          2,          3],
 [         4,         22,          6],
 [         7,          8,         33]]

nd.zip_elems supports NumPy-style broadcasting.

Input:

const
  a = nd.array([
    [1],
    [2],
    [3]
  ]),
  b = nd.array([1,2,3])

const c = nd.zip_elems([a,b], (x,y) => 10*x + y )
console.log( c.toString() )

Output:

[[        11,         12,         13],
 [        21,         22,         23],
 [        31,         32,         33]]

Ternary Operations (?:, ...)

nd.zip_elems can also be used for any n-ary operation, such as ternary conditional operator in JavaScript.

Input:

const
  flags = nd.array([true, false, false, true]),
  a = nd.array([
    [10],
    [20],
    [30],
    [40]
  ]),
  b = nd.array([1,2,3,4])

const c = nd.zip_elems([flags,a,b], (f,x,y) => f ? x : y )
console.log( c.toString() )

Output:

[[        10,          2,          3,         10],
 [        20,          2,          3,         20],
 [        30,          2,          3,         30],
 [        40,          2,          3,         40]]

Linear Algebra

nd4js now offers a fairly wide variety of Linear Algebra operations in the nd.la subpackage. la.matmul computes the matrix product of two or more matrices. The order of multiplication is automatically optimized to minimize the number of floating point operations.

Input:

const v = nd.array([[1,2,-3]]).T,
      A = nd.array([
        [1,2,3],
        [4,5,6],
        [7,8,9]
      ]);

console.log( nd.la.matmul(v.T, A, v) );

Output: