Matrix Function

Applies a function to each matrix element.

Installation

$ npm install compute-matrix-function

For use in the browser, use browserify.

Usage

var matrixfun = require( 'compute-matrix-function' );

matrixfun( fcn, ...matrix[, options] )

Applies a function to each matrix element.

var matrix = require( 'dstructs-matrix' );

var mat = matrix( [5,5], 'int8' );
/*
    [ 0 0 0 0 0
      0 0 0 0 0
      0 0 0 0 0
      0 0 0 0 0
      0 0 0 0 0 ]
*/

function add5( val ) {
	return val + 5;
}

var out = matrixfun( add5, mat );
/*
    [ 5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5 ]
*/

The function accepts the following options:

• dtype: output data type. Default: float64.
• out: boolean indicating whether an output matrix has been provided. Default: false.

By default, the output matrix data type is float64 in order to preserve precision. To specify a different data type, set the dtype option (see matrix for a list of acceptable data types).

var out = matrixfun( add5, mat, {
	'dtype': 'int8';
});
/*
    [ 5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5 ]
*/
var dtype = out.dtype;
// returns 'int8'

By default, the function returns a new matrix. To mutate a matrix (e.g., when input values can be discarded or when optimizing memory usage), set the out option to true to indicate that an output matrix has been provided as the first matrix argument.

var out = matrix( [5,5], 'int8' );
/*
    [ 0 0 0 0 0
      0 0 0 0 0
      0 0 0 0 0
      0 0 0 0 0
      0 0 0 0 0 ]
*/

matrixfun( add5, out, mat, {
	'out': 'true';
});
/*
      [ 5 5 5 5 5
        5 5 5 5 5
out =   5 5 5 5 5
        5 5 5 5 5
        5 5 5 5 5 ]
*/

===

Factory

The main exported function does not make any assumptions regarding the number of input matrices. To create a reusable matrix function where the number of input matrices is known, a factory method is provided.

matrixfun.factory( [fcn,] num[, options] )

Creates an apply function to apply a function to each matrix element.

var mfun = matrixfun.factory( 2 );

function add( x, y ) {
	return x + y;
}

var mat1 = matrix( [5,5], 'int8' ),
	mat2 = matrix( [5,5], 'int8' );

for ( var i = 0; i < 5; i++ ) {
	for ( var j = 0; j < 5; j++ ) {
		mat1.set( i, j, 5 );
		mat2.set( i, j, i*5 + j );
	}
}
/*
       [ 5 5 5 5 5
         5 5 5 5 5
mat1 =   5 5 5 5 5
         5 5 5 5 5
         5 5 5 5 5 ]

       [  0  1  2  3  4
          5  6  7  8  9
mat2 =   10 11 12 13 14
         15 16 17 18 19
         20 21 22 23 24 ]
*/

var out = mfun( add, mat1, mat2 );
/*
    [  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 ]
*/

An apply function may be provided during function creation.

var madd = matrixfun.factory( add, 2 );

var out = madd( mat1, mat2 );
/*
    [  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 ]
*/

The function accepts the following options:

• dtype: output data type. Default: float64.

By default, the output matrix data type is float64. To specify a different data type, set the dtype option.

var madd = matrixfun.factory( add, 2, {
	'dtype': 'int32';
});

var out = madd( mat1, mat2 );
/*
    [  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 ]
*/

var dtype = out.dtype;
// returns 'int32'

// ...and for all subsequent calls...
out = madd( mat1, mat2 );
dtype = out.dtype;
// returns 'int32'

Note: a factory function always returns a new matrix.

===

Create

To facilitate using matrix functions within an application where input arguments are of known types and where memory management occurs externally, a method to create minimal matrix functions is provided.

matrixfun.create( [fcn,] num )

Creates an apply function to apply a function to each matrix element, where num is the number of input matrices excluding the output matrix.

var mfcn = matrixfun.create( 2 );

var out = mfcn( add, out, mat1, mat2 );
/*
    [  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 ]
*/

function subtract( x, y ) {
	return x - y;
}

out = mfcn( subtract, out, mat2, mat1 );
/*
    [ -5 -4 -3 -2 -1
       0  1  2  3  4
       5  6  7  8  9
      10 11 12 13 14
      15 16 17 18 19 ]
*/

An apply function may be provided during function creation.

var madd = matrixfun.create( add, 2 );

var out = madd( out, mat1, mat2 );
/*
    [  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 ]
*/

===

Raw

Lower-level APIs are provided which forgo some of the guarantees of the above APIs, such as input argument validation. While use of the above APIs is encouraged in REPL environments, use of the lower-level interfaces may be warranted when arguments are of a known type or when performance is paramount.

matrixfun.raw( fcn, ...matrix[, options] )

Applies a function to each matrix element.

var mat = matrix( [5,5], 'int8' );
/*
    [ 0 0 0 0 0
      0 0 0 0 0
      0 0 0 0 0
      0 0 0 0 0
      0 0 0 0 0 ]
*/

var out = matrixfun.raw( add5, mat );
/*
    [ 5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5 ]
*/

The function accepts the same options as the main exported function.

matrixfun.rawFactory( [fcn,] num[, options] )

Creates an apply function to apply a function to each matrix element.

var mfun = matrixfun.rawFactory( 2 );

var out = mfun( add, mat1, mat2 );
/*
    [  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 ]
*/

The function accepts the same options as matrixfun.factory().

Notes

• Both factory methods, as well as the .create() method, use dynamic code evaluation. Beware when using these methods in the browser as they may violate your content security policy (CSP).

Examples

var matrix = require( 'dstructs-matrix' ),
	matrixfun = require( 'compute-matrix-function' );

var mat1,
	mat2,
	out,
	d, i;

d = new Int32Array( 25 );
for ( i = 0; i < d.length; i++ ) {
	d[ i ] = i;
}
mat1 = matrix( d, [5,5], 'int32' );
/*
    [  0  1  2  3  4
       5  6  7  8  9
      10 11 12 13 14
      15 16 17 18 19
      20 21 22 23 24 ]
*/

d = new Int8Array( 25 );
for ( i = 0; i < d.length; i++ ) {
	d[ i ] = 5;
}
mat2 = matrix( d, [5,5], 'int8' );
/*
    [ 5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5 ]
*/

function add( x, y ) {
	return x + y;
}

out = matrixfun( add, mat1, mat2 );
/*
    [  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 ]
*/
console.log( out.toString() );

To run the example code from the top-level application directory,

$ node ./examples/index.js

Tests

Unit

Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

---

License

MIT license.

Copyright

Copyright © 2015. The Compute.io Authors.