Universal Functions (ufunc)

Broadcasting
- Examples
Available Ufuncs
Methods
Optional Keyword Arguments

A universal function (or nlcpy.ufunc for short) is a function that operates on ndarrays in an element-by-element fashion, supporting array broadcasting, type casting, and several other standard features. That is, a ufunc is a “vectorized” wrapper for a function that takes a fixed number of specific inputs and produces a fixed number of specific outputs.

As with NumPy, Broadcasting rules are applied to input arrays of the universal functions of NLCPy.

Broadcasting 

Each universal function takes array inputs and produces array outputs by performing the core function element-wise on the inputs (where an element is generally a scalar, but can be a vector or higher-order sub-array for generalized ufuncs). Standard broadcasting rules are applied so that inputs not sharing exactly the same shapes can still be usefully operated on. Broadcasting can be understood by four rules:

All input arrays with ndim smaller than the input array of largest ndim, have 1’s prepended to their shapes.
The size in each dimension of the output shape is the maximum of all the input sizes in that dimension.
An input can be used in the calculation if its size in a particular dimension either matches the output size in that dimension, or has value exactly 1.
If an input has a dimension size of 1 in its shape, the first data entry in that dimension will be used for all calculations along that dimension. In other words, the stepping machinery of the ufunc will simply not step along that dimension (the stride will be 0 for that dimension).

Examples 

If a.shape is (5,1), b.shape is (1,6), c.shape is (6,) and d.shape is () so that d is a scalar, then a, b, c, and d are all broadcastable to dimension (5,6); and

a acts like a (5,6) array where a[:,0] is broadcast to the other columns,
b acts like a (5,6) array where b[0,:] is broadcast to the other rows,
c acts like a (1,6) array and therefore like a (5,6) array where c[:] is broadcast to every row, and finally,
d acts like a (5,6) array where the single value is repeated.

Available Ufuncs 

The following tables show Universal functions(ufuncs) provided by NLCPy.

Math Operations 

`nlcpy.add`	Computes the element-wise addition of the inputs.
`nlcpy.subtract`	Computes the element-wise subtraction of the inputs.
`nlcpy.multiply`	Computes the element-wise multiplication of the inputs.
`nlcpy.matmul`	Matrix product of two arrays.
`nlcpy.divide`	Computes the element-wise division of the inputs.
`nlcpy.logaddexp`	Computes the element-wise natural logarithm of $exp(x1) + exp(x2)$ .
`nlcpy.logaddexp2`	Computes the element-wise base-2 logarithm of $2^{x1} + 2^{x2}$ .
`nlcpy.true_divide`	Computes the element-wise division of the inputs.
`nlcpy.floor_divide`	Computes the element-wise floor division of the inputs.
`nlcpy.negative`	Computes numerical negative, element-wise.
`nlcpy.positive`	Computes numerical positive, element-wise.
`nlcpy.power`	Computes the element-wise exponentiation of the inputs.
`nlcpy.remainder`	Computes the element-wise remainder of division.
`nlcpy.mod`	Computes the element-wise remainder of division.
`nlcpy.fmod`	Computes the element-wise remainder of division.
`nlcpy.absolute`	Computes the element-wise absolute value.
`nlcpy.fabs`	Computes the element-wise absolute value.
`nlcpy.rint`	Computes the element-wise nearest integer.
`nlcpy.heaviside`	Computes Heaviside step function.
`nlcpy.conj`	Returns the element-wise complex conjugate.
`nlcpy.conjugate`	Returns the element-wise complex conjugate.
`nlcpy.exp`	Computes the exponential of all elements in the input array.
`nlcpy.exp2`	Computes 2**x for all elements in the array.
`nlcpy.log`	Computes the element-wise natural logarithm of x.
`nlcpy.log2`	Computes the element-wise base-2 logarithm of x.
`nlcpy.log10`	Computes the element-wise base-10 logarithm of x.
`nlcpy.log1p`	Computes the element-wise natural logarithm of 1 + x.
`nlcpy.expm1`	Computes exp(x) - 1 for all elements in the array.
`nlcpy.sqrt`	Computes the element-wise square-root of the input.
`nlcpy.square`	Computes the element-wise square of the input.
`nlcpy.cbrt`	Computes the element-wise cubic-root of the input.
`nlcpy.reciprocal`	Computes the element-wise reciprocal of the input.

Trigonometric Functions 

`nlcpy.sin`	Computes the element-wise sine.
`nlcpy.cos`	Computes the element-wise cosine.
`nlcpy.tan`	Computes the element-wise tangent.
`nlcpy.arcsin`	Computes the element-wise inverse sine.
`nlcpy.arccos`	Computes the element-wise inverse cosine.
`nlcpy.arctan`	Computes the element-wise inverse tangent.
`nlcpy.arctan2`	Computes the element-wise inverse tangent of x1/x2 choosing the quadrant correctly.
`nlcpy.hypot`	Computes the "legs" of a right triangle.
`nlcpy.sinh`	Computes the element-wise hyperbolic sine.
`nlcpy.cosh`	Computes the element-wise hyperbolic cosine.
`nlcpy.tanh`	Computes the element-wise hyperbolic tangent.
`nlcpy.arcsinh`	Computes the element-wise inverse hyperbolic sine.
`nlcpy.arccosh`	Computes the element-wise inverse hyperbolic cosine.
`nlcpy.arctanh`	Computes the element-wise inverse hyperbolic tangent.
`nlcpy.degrees`	Converts angles from radians to degrees.
`nlcpy.radians`	Converts angles from degrees to radians.
`nlcpy.deg2rad`	Converts angles from degrees to radians.
`nlcpy.rad2deg`	Converts angles from radians to degrees.

Bit-Twiddling Functions 

`nlcpy.bitwise_and`	Computes the bit-wise AND of two arrays element-wise.
`nlcpy.bitwise_or`	Computes the bit-wise OR of two arrays element-wise.
`nlcpy.bitwise_xor`	Computes the bit-wise XOR of two arrays element-wise.
`nlcpy.invert`	Computes the bit-wise NOT element-wise.
`nlcpy.left_shift`	Shifts bits of an integer to the left, element-wise.
`nlcpy.right_shift`	Shifts bits of an integer to the right, element-wise.

Comparison Functions 

`nlcpy.greater`	Returns (x1 > x2), element-wise.
`nlcpy.greater_equal`	Returns (x1 >= x2), element-wise.
`nlcpy.less`	Returns (x1 < x2), element-wise.
`nlcpy.less_equal`	Returns (x1 <= x2), element-wise.
`nlcpy.not_equal`	Returns (x1 != x2), element-wise.
`nlcpy.equal`	Returns (x1 == x2), element-wise.
`nlcpy.logical_and`	Computes the logical AND of two arrays element-wise.
`nlcpy.logical_or`	Computes the logical OR of two arrays element-wise.
`nlcpy.logical_xor`	Computes the logical XOR of two arrays element-wise.
`nlcpy.logical_not`	Computes the logical NOT of the input array element-wise.
`nlcpy.maximum`	Computes the element-wise maximum of the inputs.
`nlcpy.minimum`	Computes the element-wise minimum of the inputs.
`nlcpy.fmax`	Computes the element-wise maximum of the inputs.
`nlcpy.fmin`	Computes the element-wise minimum of the inputs.

Floating Point Functions 

`nlcpy.isfinite`	Tests whether input elements are neither inf nor nan, or not.
`nlcpy.isinf`	Tests whether input elements are inf, or not.
`nlcpy.isnan`	Tests whether input elements are nan, or not.
`nlcpy.signbit`	Returns True where signbit is set (less than zero), element-wise.
`nlcpy.copysign`	Changes the sign of x1 to that of x2, element-wise.
`nlcpy.sign`	Returns the element-wise indication of the sign of a number.
`nlcpy.nextafter`	Returns the next floating-point value after x1 towards x2, element-wise.
`nlcpy.spacing`	Returns the distance between x and the nearest adjacent number, element-wise.
`nlcpy.ldexp`	Returns $x1 * 2^{x2}$ , element-wise.
`nlcpy.floor`	Returns the floor of the input, element-wise.
`nlcpy.ceil`	Returns the ceiling of the input, element-wise.
`nlcpy.trunc`	Returns the truncated value of the input, element-wise.

Methods 

In NLCPy, ufuncs are instances of the nlcpy.ufunc class. nlcpy.ufunc have four methods. However, these methods only make sense on scalar ufuncs that take two input arguments and return one output argument. Attempting to call these methods on other ufuncs will cause a ValueError.

`nlcpy.ufunc.reduce`	Reduces one of the dimension of the input array, by applying ufunc along one axis.
`nlcpy.ufunc.accumulate`	Accumulates the result of applying the operator to all elements.
`nlcpy.ufunc.reduceat`	Performs a (local) reduce with specified slices over a single axis.
`nlcpy.ufunc.outer`	Applies the ufunc op to all pairs (a, b) with a in A and b in B.

The current version of NLCPy does not provide nlcpy.ufunc.at(), which is supported by NumPy.

Optional Keyword Arguments 

All ufuncs take optional keyword arguments. Most of these represent advanced usage and will not typically be used.

out

A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs.

where

This condition is broadcast over the input. At locations where the condition is True, the out array will be set to the ufunc result. Elsewhere, the out array will retain its original value. Note that if an uninitialized out array is created via the default out=None, locations within it where the condition is False will remain uninitialized.

casting

Controls what kind of data casting may occur.

‘no’ means the data types should not be cast at all.

‘equiv’ means only byte-order changes are allowed.

‘safe’ means only casts which can preserve values are allowed.

‘same_kind’ means only safe casts or casts within a kind, like float64 to float32, are allowed.

NLCPy does NOT support ‘unsafe’, which is supported in NumPy.

order

Specifies the calculation iteration order/memory layout of the output array. Defaults to ‘K’. ‘C’ means the output should be C-contiguous, ‘F’ means F-contiguous, ‘A’ means F-contiguous if the inputs are F-contiguous and not also not C-contiguous, C-contiguous otherwise, and ‘K’ means to match the element ordering of the inputs as closely as possible.

dtype

Overrides the dtype of the calculation and output arrays.

subok

Not implemented in NLCPy.