Home

Awesome

cwise

This library can be used to generate cache efficient map/reduce operations for ndarrays.

build status

Examples

For brevity, we will assume the following precedes each example:

//Import libraries
var cwise = require("cwise")
  , ndarray = require("ndarray")

Adding two arrays

The array equivalent of +=:

//Create operation
var addeq = cwise({
    args: ["array", "array"],
    body: function(a, b) {
      a += b
    }
  })

//Create two 2D arrays
var X = ndarray(new Float32Array(128*128), [128,128])
var Y = ndarray(new Float32Array(128*128), [128,128])

//Add them together
addeq(X, Y)

Formally, you can think of addeq(X,Y) as being something like the following for-loop, except optimized with respect to the dimension and order of X and Y:

for(var i=0; i<X.shape[0]; ++i) {
  for(var j=0; j<X.shape[1]; ++j) {
    X.set(i,j, X.get(i,j) + Y.get(i,j))
  }
}

Multiply an array with a scalar

var muls = cwise({
  args: ["array", "scalar"],
  body: function(a, s) {
    a *= s
  }
})

//Example usage:
muls(array, 2.0)

Initialize an array with a grid with the first index

var mgrid = cwise({
  args: ["index", "array"],
  body: function(i, a) {
    a = i[0]
  }
})

//Example usage:
var X = mgrid(ndarray(new Float32Array(128)))

Compute 2D vector norms using blocks

var norm2D = cwise({
  args: ["array", {blockIndices: -1}],
  body: function(o, i) {
    o = Math.sqrt(i[0]*i[0] + i[1]*i[1])
  }
})

//Example usage:
var o = ndarray([0, 0, 0], [3])
norm2D(o, ndarray([1, 2, 3, 4, 5, 6], [3,2]))
// o.data == [ 2.23606797749979, 5, 7.810249675906654 ]

Note that in the above, i is not an actual Array, the indexing notation is just syntactic sugar.

Apply a stencil to an array

var laplacian = cwise({
  args:["array", "array", {offset:[0,1], array:1}, {offset:[0,-1], array:1}, {offset:[1,0], array:1}, {offset:[-1,0], array:1}],
  body:function(a, c, n, s, e, w) {
    a = 0.25 * (n + s + e + w) - c
  }
})

laplacian(next, prev)

Compute the sum of all the elements in an array

var sum = cwise({
  args: ["array"],
  pre: function() {
    this.sum = 0
  },
  body: function(a) {
    this.sum += a
  },
  post: function() {
    return this.sum
  }
})
  
//Usage:
s = sum(array)

Note that variables stored in this are common to all three code blocks. Also note that one should not treat this as an actual object (for example, one should not attempt to return this).

Check if any element is set

var any = cwise({
  args: ["array"],
  body: function(a) {
    if(a) {
      return true
    }
  },
  post: function() {
    return false
  }
})

//Usage
if(any(array)) {
  // ...
}

Compute the index of the maximum element of an array:

var argmin = cwise({
  args: ["index", "array"],
  pre: function(index) {
    this.min_v = Number.POSITIVE_INFINITY
    this.min_index = index.slice(0)
  },
  body: function(index, a) {
    if(a < this.min_v) {
      this.min_v = a
      for(var i=0; i<index.length; ++i) {
        this.min_index[i] = index[i]
      }
    }
  },
  post: function() {
    return this.min_index
  }
})

//Usage:
argmin(X)

Install

Install using npm:

npm install cwise

API

require("cwise")(user_args)

To use the library, you pass it an object with the following fields:

The result is a procedure that you can call which executes these methods along the following lines:

function(a0, a1, ...) {
  pre()
  for(var i=0; i<a0.shape[0]; ++i) {
    for(var j=0; j<a0.shape[1]; ++j) {
      ...
      
          body(a0[i,j,...], a1[i,j,...], ... )
    }
  }
  post()
}

Notes

As a browserify transform

If bundle size is an issue for you, it is possible to use cwise as a browserify transform, thus avoiding the potentially large parser dependencies. To do this, add the following lines to your package.json:

//Contents of package.json
{
    // ...

    "browserify": {
      "transform": [ "cwise" ]
    }

    // ...
}

Then when you use the module with browserify, only the cwise-compile submodule will get loaded into your script instead of all of esprima. Note that this step is optional and the library will still work in the browser even if you don't use a transform.

FAQ

Is it fast?

Yes

How does it work?

You can think of cwise as a type of macro language on top of JavaScript. Internally, cwise uses node-falafel to parse the functions you give it and sanitize their arguments. At run time, code for each array operation is generated lazily depending on the ordering and stride of the input arrays so that you get optimal cache performance. These compiled functions are then memoized for future calls to the same function. As a result, you should reuse array operations as much as possible to avoid wasting time and memory regenerating common functions.

License

(c) 2013 Mikola Lysenko. MIT License