Skip to content

improvess/matrix-reef.js

Repository files navigation

Build Status Coverage Status Version Maintenance License

A faster Matrix for the Java Script World.

There are pretty awesome matrix libraries for Java Script in the wild. But if you are looking for something faster consider using this library. Matrix-reef.js is a pure Java Script matrix library for numeric computing. It is extremely fast and there is no third-party dependencies under the wood (no webgl!). Check out the comparison below.

Benchmarks

This table shows the amount of operations per second achieved by Matrix-reef.js and 3 other popular libraries on multiplying squared matrices:

2x2 3x3 4x4 16x16 32x32 256x256 512x512 1024x1024
Matrix-reef JS 12,525,475 7,767,275 4,264,070 192,831 31,382 95.34 10.25 1.73
Alternative M 692,706 640,598 418,942 73,875 18,161 45.08 5.40 0.69
Alternative S 2,704,288 1,260,948 500,337 13,602 1,847 3.81 0.33 0.04
Alternative J 452,393 388,227 230,914 11,256 1,496 2.84 0.27 0.01

I got these results on V8/node10.19 @ ubuntu 20.04 with 2-cpu and 8GB RAM over virtualbox.

The performance keeps fast when matrices are not squared:

2x1 3x1 4x1 16x8 32x16 256x64 512x256 1024x512
Matrix-reef JS 16,117,191 8,535,501 6,016,547 302,954 53,428 193.00 21.14 1.73
Alternative M 742,676 690,738 540,807 84,639 27,066 162.00 12.42 0.69
Alternative S 1,521,298 1,050,874 737,126 32,864 4,267 10.49 0.88 0.04
Alternative J 519,801 445,270 337,309 20,527 2,717 13.49 0.53 0.01

The label 4x1 means multiply one 4x1 matrix by another 1x4. See Running the benchmarks for more details.

What is the trick? Some libraries are really complete in terms of functionalities, supporting things such as non numerics elements, complex numbers and other very important features. All those requirements seem to come with a price in terms of performance. On the other hand, Matrix-reef.js has only a small - but powerful - subset of features.

How to use

const A = new Matrix([
    [1, 2], 
    [3, 4], 
    [5, 6]
]); // create a 3x2 matrix

const B = new Matrix([
    [2, 1], 
    [2, 0]
]); // create a 2x2 matrix

const C = A.multiply(B);

See examples below for a full list of functionalities.

How to install

Matrix-reef.js has no third-party, dependency to install.

Node.js

$ npm install matrix-reef.js

and include

const { Matrix } = require('matrix-reef.js');

CDN

<script src="https://cdn.jsdelivr.net/npm/[email protected]/index.min.js"></script>

API by examples

Matrix-reef.js API is very streamline. Check out the examples below:

PS.: Some features are not available yet.

Real world examples

This example shows how to train a neural network using Iris dataset and only add, multiply, dotMultiply, map and transpose. You can run it by executing the following command:

$ node examples/training.ann.js 

THe output should be like:

Elapsed time: 0.81 secs for 5000 epochs.

Running the benchmarks

There are several ways to evaluate a library. Here we are focused on throughput (that is, operations/sec). The code for this benchmark is here. It uses Benchmark.js to compare the performance of Matrix-reef.js and three other Java Script matrix libraries.

To run the benchmark is easy. Just execute the following command to run a benchmark yourself:

node benchmarks/multiplication.js 10 4 10 5

The example above executes chunks of 10 4x10 by 10x5 matrix multiplications.

Disclaimer

I'm working hard on this but I'm afraid that Matrix-reef.js is still in the early stages and likely to do not be ready for production yet. My todo list is in the issues section.

New features, bugs and collaboration

Do not hesitate to open a new issue whenever you find something wrong or does not working as expected. Suggestions of new features are pretty welcome as well as collaborations by PR test cases, benchmarks or even new features.