API reference

Universal functions (ufunc)

A universal function (ufunc) operates on arrays element by element. It supports broadcasting, type promotion and a set of standard options. Like NumPy's, numera's ufuncs are callable objects: np.add(a, b) computes, and np.add.reduce(a) reduces with the same operation.

JavaScript

np.add([1, 2, 3], 10);              // => [11, 12, 13]
np.sqrt([1, 4, 9]);                 // => [1, 2, 3]
np.add.reduce([1, 2, 3]).item();    // => 6

Broadcasting#

Inputs of different shapes are broadcast against each other using NumPy's rules: dimensions are compared from the last one, and each pair must be equal or contain a 1. Incompatible shapes raise BroadcastError.

JavaScript

np.add(np.ones([3, 1]), np.arange(4)).shape;  // => [3, 4]
np.multiply([[1], [2]], [10, 20]);            // => [[10, 20], [20, 40]]

Output type determination#

The result dtype comes from NumPy's promotion of the input dtypes. JS numbers are weak scalars (NEP 50), so they don't widen an array's dtype. See Data types.

JavaScript

np.add(np.array([1], { dtype: "int8" }), 1).dtype.name;     // => "int8"
np.add(np.array([1], { dtype: "int8" }), 1.5).dtype.name;   // => "float64"
np.divide([1, 2], 2).dtype.name;                            // => "float64"
np.add([1, 2], [3, 4], { dtype: "float32" }).dtype.name;    // => "float32"

Optional arguments#

Every ufunc accepts an options object as its last argument:

Option	NumPy	Meaning
`out`	`out=`	write the result into this array and return it
`where`	`where=`	boolean mask: compute only where `true`
`dtype`	`dtype=`	loop dtype: inputs are cast to it and the result has it
`casting`	`casting=`	casting rule for inputs and `out` (default `"same_kind"`)
`order`	`order=`	memory layout of a new result: `"K"` (default), `"C"`, `"F"` or `"A"`

JavaScript

const o = np.zeros(3);
np.multiply([1, 2, 3], 2, { out: o }) === o;  // => true
o;                                            // => [2, 4, 6]

const w = np.full([3], -1.0, { dtype: "float64" });
np.sqrt([1, 4, 9], { out: w, where: [true, false, true] });
w;                                            // => [1, -1, 3]

Without out, positions where where is false are zero-filled. NumPy leaves them uninitialised. Writing a result into an out array of a lower kind is checked with casting:

JavaScript

let msg;
try { np.add(np.array([1.5]), 1, { out: np.zeros(1, { dtype: "int32" }) }); } catch (e) { msg = e.message; }
msg; // => "Cannot cast ufunc 'add' output from float64 to int32 with casting rule 'same_kind'"

Methods#

Binary ufuncs (two inputs, one output) have NumPy's five methods:

Method	NumPy	Meaning
`reduce(a, { axis, dtype, out, keepdims, initial, where })`	`ufunc.reduce`	combine along an axis
`accumulate(a, { axis, dtype, out })`	`ufunc.accumulate`	running reduction
`reduceat(a, indices, { axis, dtype, out })`	`ufunc.reduceat`	reductions over slices
`outer(a, b)`	`ufunc.outer`	apply to every pair
`at(a, indices, b)`	`ufunc.at`	unbuffered in-place operation

Unary ufuncs have at(a, indices).

JavaScript

np.maximum.reduce([[1, 5], [4, 2]], { axis: 1 }); // => [5, 4]
np.add.accumulate([1, 2, 3]);                     // => [1, 3, 6]
np.add.reduceat([1, 2, 3, 4], [0, 2]);            // => [3, 7]
np.multiply.outer([1, 2, 3], [1, 10]);            // => [[1, 10], [2, 20], [3, 30]]

const c = np.array([1, 2, 3, 4]);
np.add.at(c, [0, 0, 1], 10);                      // repeated indices accumulate
c;                                                // => [21, 12, 3, 4]

Floating-point errors#

Division by zero, overflow, underflow and invalid operations are handled according to np.seterr / np.errstate. By default they emit a RuntimeWarning, and they can be ignored or raised instead. See Errors and floating-point.

JavaScript

np.errstate({ divide: "ignore" }, () => np.divide([1, -1], [0, 0]).toArray().map(String)); // => ["Infinity", "-Infinity"]

Available ufuncs#

numera 1.0.2 implements 106 of NumPy's ufuncs. The descriptions are NumPy's one-line summaries, and each NumPy name links to its page on numpy.org.

Math operations#

numera	NumPy	Kind	Description
`np.abs`	`abs`	unary · at	Calculate the absolute value element-wise.
`np.absolute`	`absolute`	unary · at	Calculate the absolute value element-wise.
`np.add`	`add`	binary · reduce, accumulate, reduceat, outer, at	Add arguments element-wise.
`np.cbrt`	`cbrt`	unary · at	Return the cube-root of an array, element-wise.
`np.conj`	`conj`	unary	Return the complex conjugate, element-wise.
`np.conjugate`	`conjugate`	unary	Return the complex conjugate, element-wise.
`np.divide`	`divide`	binary · reduce, accumulate, reduceat, outer, at	Divide arguments element-wise.
`np.divmod`	`divmod`	binary	Return element-wise quotient and remainder simultaneously.
`np.exp`	`exp`	unary · at	Calculate the exponential of all elements in the input array.
`np.exp2`	`exp2`	unary · at	Calculate `2**p` for all `p` in the input array.
`np.expm1`	`expm1`	unary · at	Calculate `exp(x) - 1` for all elements in the array.
`np.fabs`	`fabs`	unary · at	Compute the absolute values element-wise.
`np.floatPower`	`float_power`	binary · reduce, accumulate, reduceat, outer, at	First array elements raised to powers from second array, element-wise.
`np.floorDivide`	`floor_divide`	binary · reduce, accumulate, reduceat, outer, at	Return the largest integer smaller or equal to the division of the inputs. It is equivalent to the Python `//` operator and pairs with the Python `%` (`remainder`), function so that `a = a % b + b * (a // b)` up to roundoff.
`np.fmod`	`fmod`	binary · reduce, accumulate, reduceat, outer, at	Returns the element-wise remainder of division.
`np.gcd`	`gcd`	binary · reduce, accumulate, reduceat, outer, at	Returns the greatest common divisor of `\|x1\|` and `\|x2\|`
`np.heaviside`	`heaviside`	binary · reduce, accumulate, reduceat, outer, at	Compute the Heaviside step function.
`np.lcm`	`lcm`	binary · reduce, accumulate, reduceat, outer, at	Returns the lowest common multiple of `\|x1\|` and `\|x2\|`
`np.log`	`log`	unary · at	Natural logarithm, element-wise.
`np.log10`	`log10`	unary · at	Return the base 10 logarithm of the input array, element-wise.
`np.log1p`	`log1p`	unary · at	Return the natural logarithm of one plus the input array, element-wise.
`np.log2`	`log2`	unary · at	Base-2 logarithm of `x`.
`np.logaddexp`	`logaddexp`	binary · reduce, accumulate, reduceat, outer, at	Logarithm of the sum of exponentiations of the inputs.
`np.logaddexp2`	`logaddexp2`	binary · reduce, accumulate, reduceat, outer, at	Logarithm of the sum of exponentiations of the inputs in base-2.
`np.matmul`	`matmul`	binary	Matrix product of two arrays.
`np.matvec`	`matvec`	binary	Matrix-vector dot product of two arrays.
`np.mod`	`mod`	binary · reduce, accumulate, reduceat, outer, at	Returns the element-wise remainder of division.
`np.multiply`	`multiply`	binary · reduce, accumulate, reduceat, outer, at	Multiply arguments element-wise.
`np.negative`	`negative`	unary · at	Numerical negation, element-wise.
`np.positive`	`positive`	unary · at	Numerical positive, element-wise.
`np.pow`	`pow`	binary · reduce, accumulate, reduceat, outer, at	First array elements raised to powers from second array, element-wise.
`np.power`	`power`	binary · reduce, accumulate, reduceat, outer, at	First array elements raised to powers from second array, element-wise.
`np.reciprocal`	`reciprocal`	unary · at	Return the reciprocal of the argument, element-wise.
`np.remainder`	`remainder`	binary · reduce, accumulate, reduceat, outer, at	Returns the element-wise remainder of division.
`np.rint`	`rint`	unary · at	Round elements of the array to the nearest integer.
`np.sign`	`sign`	unary · at	Returns an element-wise indication of the sign of a number.
`np.sqrt`	`sqrt`	unary · at	Return the non-negative square-root of an array, element-wise.
`np.square`	`square`	unary · at	Return the element-wise square of the input.
`np.subtract`	`subtract`	binary · reduce, accumulate, reduceat, outer, at	Subtract arguments, element-wise.
`np.trueDivide`	`true_divide`	binary · reduce, accumulate, reduceat, outer, at	Divide arguments element-wise.
`np.vecdot`	`vecdot`	binary	Vector dot product of two arrays.
`np.vecmat`	`vecmat`	binary	Vector-matrix dot product of two arrays.

Trigonometric functions#

numera	NumPy	Kind	Description
`np.acos`	`acos`	unary · at	Trigonometric inverse cosine, element-wise.
`np.acosh`	`acosh`	unary · at	Inverse hyperbolic cosine, element-wise.
`np.arccos`	`arccos`	unary · at	Trigonometric inverse cosine, element-wise.
`np.arccosh`	`arccosh`	unary · at	Inverse hyperbolic cosine, element-wise.
`np.arcsin`	`arcsin`	unary · at	Inverse sine, element-wise.
`np.arcsinh`	`arcsinh`	unary · at	Inverse hyperbolic sine, element-wise.
`np.arctan`	`arctan`	unary · at	Trigonometric inverse tangent, element-wise.
`np.arctan2`	`arctan2`	binary · reduce, accumulate, reduceat, outer, at	Element-wise arc tangent of `x1/x2` choosing the quadrant correctly.
`np.arctanh`	`arctanh`	unary · at	Inverse hyperbolic tangent, element-wise.
`np.asin`	`asin`	unary · at	Inverse sine, element-wise.
`np.asinh`	`asinh`	unary · at	Inverse hyperbolic sine, element-wise.
`np.atan`	`atan`	unary · at	Trigonometric inverse tangent, element-wise.
`np.atan2`	`atan2`	binary · reduce, accumulate, reduceat, outer, at	Element-wise arc tangent of `x1/x2` choosing the quadrant correctly.
`np.atanh`	`atanh`	unary · at	Inverse hyperbolic tangent, element-wise.
`np.cos`	`cos`	unary · at	Cosine element-wise.
`np.cosh`	`cosh`	unary · at	Hyperbolic cosine, element-wise.
`np.deg2rad`	`deg2rad`	unary · at	Convert angles from degrees to radians.
`np.degrees`	`degrees`	unary · at	Convert angles from radians to degrees.
`np.hypot`	`hypot`	binary · reduce, accumulate, reduceat, outer, at	Given the "legs" of a right triangle, return its hypotenuse.
`np.rad2deg`	`rad2deg`	unary · at	Convert angles from radians to degrees.
`np.radians`	`radians`	unary · at	Convert angles from degrees to radians.
`np.sin`	`sin`	unary · at	Trigonometric sine, element-wise.
`np.sinh`	`sinh`	unary · at	Hyperbolic sine, element-wise.
`np.tan`	`tan`	unary · at	Compute tangent element-wise.
`np.tanh`	`tanh`	unary · at	Hyperbolic tangent, element-wise.

Bit-twiddling functions#

numera	NumPy	Kind	Description
`np.bitwiseAnd`	`bitwise_and`	binary · reduce, accumulate, reduceat, outer, at	Compute the bit-wise AND of two arrays element-wise.
`np.bitwiseCount`	`bitwise_count`	unary · at	Computes the number of 1-bits in the absolute value of `x`. Analogous to the builtin `int.bit_count` or `popcount` in C++.
`np.bitwiseInvert`	`bitwise_invert`	unary · at	Compute bit-wise inversion, or bit-wise NOT, element-wise.
`np.bitwiseLeftShift`	`bitwise_left_shift`	binary · reduce, accumulate, reduceat, outer, at	Shift the bits of an integer to the left.
`np.bitwiseNot`	`bitwise_not`	unary · at	Compute bit-wise inversion, or bit-wise NOT, element-wise.
`np.bitwiseOr`	`bitwise_or`	binary · reduce, accumulate, reduceat, outer, at	Compute the bit-wise OR of two arrays element-wise.
`np.bitwiseRightShift`	`bitwise_right_shift`	binary · reduce, accumulate, reduceat, outer, at	Shift the bits of an integer to the right.
`np.bitwiseXor`	`bitwise_xor`	binary · reduce, accumulate, reduceat, outer, at	Compute the bit-wise XOR of two arrays element-wise.
`np.invert`	`invert`	unary · at	Compute bit-wise inversion, or bit-wise NOT, element-wise.
`np.leftShift`	`left_shift`	binary · reduce, accumulate, reduceat, outer, at	Shift the bits of an integer to the left.
`np.rightShift`	`right_shift`	binary · reduce, accumulate, reduceat, outer, at	Shift the bits of an integer to the right.

Comparison functions#

numera	NumPy	Kind	Description
`np.equal`	`equal`	binary · reduce, accumulate, reduceat, outer, at	Return (x1 == x2) element-wise.
`np.fmax`	`fmax`	binary · reduce, accumulate, reduceat, outer, at	Element-wise maximum of array elements.
`np.fmin`	`fmin`	binary · reduce, accumulate, reduceat, outer, at	Element-wise minimum of array elements.
`np.greater`	`greater`	binary · reduce, accumulate, reduceat, outer, at	Return the truth value of (x1 > x2) element-wise.
`np.greaterEqual`	`greater_equal`	binary · reduce, accumulate, reduceat, outer, at	Return the truth value of (x1 >= x2) element-wise.
`np.less`	`less`	binary · reduce, accumulate, reduceat, outer, at	Return the truth value of (x1 < x2) element-wise.
`np.lessEqual`	`less_equal`	binary · reduce, accumulate, reduceat, outer, at	Return the truth value of (x1 <= x2) element-wise.
`np.logicalAnd`	`logical_and`	binary · reduce, accumulate, reduceat, outer, at	Compute the truth value of x1 AND x2 element-wise.
`np.logicalNot`	`logical_not`	unary · at	Compute the truth value of NOT x element-wise.
`np.logicalOr`	`logical_or`	binary · reduce, accumulate, reduceat, outer, at	Compute the truth value of x1 OR x2 element-wise.
`np.logicalXor`	`logical_xor`	binary · reduce, accumulate, reduceat, outer, at	Compute the truth value of x1 XOR x2, element-wise.
`np.maximum`	`maximum`	binary · reduce, accumulate, reduceat, outer, at	Element-wise maximum of array elements.
`np.minimum`	`minimum`	binary · reduce, accumulate, reduceat, outer, at	Element-wise minimum of array elements.
`np.notEqual`	`not_equal`	binary · reduce, accumulate, reduceat, outer, at	Return (x1 != x2) element-wise.

Floating functions#

numera	NumPy	Kind	Description
`np.ceil`	`ceil`	unary · at	Return the ceiling of the input, element-wise.
`np.copysign`	`copysign`	binary · reduce, accumulate, reduceat, outer, at	Change the sign of x1 to that of x2, element-wise.
`np.floor`	`floor`	unary · at	Return the floor of the input, element-wise.
`np.frexp`	`frexp`	binary	Decompose the elements of x into mantissa and twos exponent.
`np.isfinite`	`isfinite`	unary · at	Test element-wise for finiteness (not infinity and not Not a Number).
`np.isinf`	`isinf`	unary · at	Test element-wise for positive or negative infinity.
`np.isnan`	`isnan`	unary · at	Test element-wise for NaN and return result as a boolean array.
`np.isnat`	`isnat`	unary · at	Test element-wise for NaT (not a time) and return result as a boolean array.
`np.ldexp`	`ldexp`	binary · reduce, accumulate, reduceat, outer, at	Returns x1 * 2**x2, element-wise.
`np.modf`	`modf`	binary	Return the fractional and integral parts of an array, element-wise.
`np.nextafter`	`nextafter`	binary · reduce, accumulate, reduceat, outer, at	Return the next floating-point value after x1 towards x2, element-wise.
`np.signbit`	`signbit`	unary · at	Returns element-wise True where signbit is set (less than zero).
`np.spacing`	`spacing`	unary · at	Return the distance between x and the nearest adjacent number.
`np.trunc`	`trunc`	unary · at	Return the truncated value of the input, element-wise.