ndarray-ops

ndarray-ops
===========
A collection of common mathematical operations for ndarrays. Implemented using cwise

Usage
=====
First, install the library using npm:

npm install ndarray-ops

Then you can import the library by doing:

var ops = require("ndarray-ops")

Then you can use the functions as in the following example:

``javascript
//First, import libraries
var ndarray = require("ndarray")
, ops = require("ndarray-ops")


//Next, create some arrays
var a = ndarray(new Float32Array(128*128))
, b = ndarray(new Float32Array(128*128))
, c = ndarray(new Float32Array(128*128))

//Initialize b with some random numbers:
ops.random(b)

//Set c to a constant 1
ops.assigns(c, 1.0)

//Add b and c, store result in a:
ops.add(a, b, c)

//Multiply a by 0.5 in place
ops.mulseq(a, 0.5)

//Print some statistics about a:
console.log(
"inf(a) = ", ops.inf(a),
"sup(a) = ", ops.sup(a),
"argmin(a) = ", ops.argmin(a),
"argmax(a) = ", ops.argmax(a),
"norm1(a) = ", ops.norm1(a))
`

Conventions
===========
This library implements component-wise operations for all of the operators and Math.* functions in JS, along with a few commonly used aggregate operations. Most of the functions in the library work by applying some symmetric binary operator to a pair of arrays. You call them like this:

`javascript
ops.add(dest, arg1, arg2)
`

Which translates into code that works (approximately) like this:

`javascript
for(var i=0; i dest[i] = arg1[i] + arg2[i]
}
`

It is up to you to specify where the result gets store. This library does not create new arrays for you to avoid performing expensive intermediate allocations. There are also a few other variations:

`javascript
ops.addeq(dest, arg1)
`
Operators with the -eq suffix perform an assignment.

`javascript
for(var i=0; i dest[i] += arg1[i]
}
`

`javascript
ops.adds(dest, arg1, 1.0)
`
The -s suffix denotes scalar/broadcast operations; so the above would translate to:

`javascript
for(var i=0; i dest[i] = arg1[i] + 1.0
}
`

`javascript
ops.addseq(dest, 1.0)
`
The -seq suffix is basically the combination of the above, and translates to:

`javascript
for(var i=0; i dest[i] += 1.0
}
`

The following operators follow this rule:

* add[,s,eq,seq] - Addition, +
* sub[,s,eq,seq] - Subtraction, -
mul[,s,eq,seq] - Multiplication,
* div[,s,eq,seq] - Division, /
* mod[,s,eq,seq] - Modulo, %
* band[,s,eq,seq] - Bitwise And, &
* bor[,s,eq,seq] - Bitwise Or, &
* bxor[,s,eq,seq] - Bitwise Xor, ^
* lshift[,s,eq,seq] - Left shift, <<
* rshift[,s,eq,seq] - Signed right shift, >>
* rrshift[,s,eq,seq] - Unsigned right shift, >>>
* lt[,s,eq,seq] - Less than, <
* gt[,s,eq,seq] - Greater than, >
* leq[,s,eq,seq] - Less than or equal, <=
* geq[,s,eq,seq] - Greater than or equal >=
* eq[,s,eq,seq] - Equals, ===
* neq[,s,eq,seq] - Not equals, !==
* and[,s,eq,seq] - Boolean And, &&
* or[,s,eq,seq] - Boolean Or, ||
* max[,s,eq,seq] - Maximum, Math.max
* min[,s,eq,seq] - Minimum, Math.min


Special Cases
-------------
There are a few corner cases that follow slightly different rules. These can be grouped using the following general categories:

$3

There are two assignment operators:

* assign
* assigns

op.assign(dest, src) copies one array into another, while op.assigns(dest, val) broadcasts a scalar to all elements of an array.

$3

Nullary operators only take on argument for the array they are assigning to, and don't have any variations. Currently there is only one of these:

* random - Sets each element of an array to a random scalar between 0 and 1, Math.random()

$3

Unary operators have one of two forms, they can be written as either:

`javascript
op.abs(dest, arg)
`

Or:

`javascript
op.abseq(dest)
`

The former version sets dest = |arg|, while in the latter the operation is applied in place. ndarray-ops exposes the following unary operators:

* not[,eq] - Boolean not, !
* bnot[,eq] - Bitwise not, ~
* neg[,eq] - Negative, -
* recip[,eq] - Reciprocal, 1.0/
* abs[,eq] - Absolute value, Math.abs
* acos[,eq] - Inverse cosine, Math.acos
* asin[,eq] - Inverse sine, Math.asin
* atan[,eq] - Inverse tangent, Math.atan
* ceil[,eq] - Ceiling, Math.ceil
* cos[,eq] - Cosine, Math.cos
* exp[,eq] - Exponent, Math.exp
* floor[,eq] - Floor, Math.floor
* log[,eq] - Logarithm, Math.log
* round[,eq] - Round, Math.round
* sin[,eq] - Sine, Math.sin
* sqrt[,eq] - Square root, Math.sqrt
* tan[,eq] - Tangent, Math.tan

$3


There are also a few non-symmetric binary operators. These operators have an extra suffix op` which flips the order of the arguments. There are only two of these:

* atan2[,s,eq,seq,op,sop,opeq,sopeq]
* pow[,s,eq,seq,op,sop,opeq,sopeq]

$3

Finally, there are aggregate operators that take an array as input and compute some aggregate result or summary. These functions don't have any special suffixes and all of them take a single array as input.

* equals - Check if two ndarrays are equal
* any - Check if any element of the array is truthy
* all - Checks if any element of the array is falsy
* sum - Sums all elements of the array
* prod - Multiplies all elements of the array
* norm2squared - Computes the squared L2 norm
* norm2 - Computes the L2 norm
* norminf - Computes the L-infinity norm
* norm1 - Computs the L1 norm
* sup - Max element in array
* inf - Min element in array
* argmin - Index of min element
* argmax - Index of max element

Credits
=======
(c) 2013 Mikola Lysenko. MIT License