numeric¶

The numeric module provides methods that are lacking from the numpy module.

nutils.numeric.overlapping(arr, axis=-1, n=2)¶: reinterpret data with overlaps

nutils.numeric.normdim(ndim, n)¶: check bounds and make positive

nutils.numeric.get(arr, axis, item)¶: take single item from array axis

nutils.numeric.contract(A, B, axis=-1)¶

nutils.numeric.dot(A, B, axis=-1)¶: Transform axis of A by contraction with first axis of B and inserting remaining axes. Note: with default axis=-1 this leads to multiplication of vectors and matrices following linear algebra conventions.

nutils.numeric.meshgrid(*args)¶: multi-dimensional meshgrid generalisation

nutils.numeric.normalize(A, axis=-1)¶: devide by normal

nutils.numeric.diagonalize(arg, axis=-1, newaxis=-1)¶: insert newaxis, place axis on diagonal of axis and newaxis

nutils.numeric.inv(A)¶

Matrix inverse.

Fully equivalent to numpy.linalg.inv(), with the exception that upon singular systems inv() does not raise a LinAlgError, but rather issues a RuntimeWarning and returns NaN (not a number) values. For arguments of dimension >2 the return array contains NaN values only for those entries that correspond to singular matrices.

nutils.numeric.ix(args)¶: version of numpy.ix_() that allows for scalars

nutils.numeric.ext(A)¶: Exterior For array of shape (n,n-1) return n-vector ex such that ex.array = 0 and det(arr;ex) = ex.ex

nutils.numeric.unpack(n, atol, rtol)¶

Convert packed representation to floating point data.

The packed binary form is a floating point interpretation of signed integer data, such that any integer n maps onto float a as follows:

a = nan                       if n = -N-1
a = -inf                      if n = -N
a = sinh(n*rtol)*atol/rtol    if -N < n < N
a = +inf                      if n = N,

where N = 2**(nbits-1)-1 is the largest representable signed integer.

Note that packing is both order and zero preserving. The transformation is designed such that the spacing around zero equals atol, while the relative spacing for most of the data range is approximately constant at rtol. Precisely, the spacing between a value a and the adjacent value is sqrt(atol**2 + (a*rtol)**2). Note that the truncation error equals half the spacing.

The representable data range depends on the values of atol and rtol and the bitsize of n. Useful values for different data types are:

dtype	rtol	atol	range
int8	2e-1	2e-06	4e+05
int16	2e-3	2e-15	1e+16
int32	2e-7	2e-96	2e+97

Parameters

n (int array) – Integer data.
atol (float) – Absolute tolerance.
rtol (float) – Relative tolerance.

Returns

Return type

float array

nutils.numeric.pack(a, atol, rtol, dtype)¶

Lossy compression of floating point data.

See unpack() for the definition of the packed binary form. The converse transformation uses rounding in packed domain to determine the closest matching value. In particular this may lead to values falling outside the representable data range to be clipped to infinity. Some examples of packed truncation:

>>> def truncate(a, dtype, **tol):
...   return unpack(pack(a, dtype=dtype, **tol), **tol)
>>> truncate(0.5, dtype='int16', atol=2e-15, rtol=2e-3)
0.5004...
>>> truncate(1, dtype='int16', atol=2e-15, rtol=2e-3)
0.9998...
>>> truncate(2, dtype='int16', atol=2e-15, rtol=2e-3)
2.0013...
>>> truncate(2, dtype='int16', atol=2e-15, rtol=2e-4)
inf
>>> truncate(2, dtype='int32', atol=2e-15, rtol=2e-4)
2.00013...

Parameters

a (float array) – Input data.
atol (float) – Absolute tolerance.
rtol (float) – Relative tolerance.
dtype (str or numpy dtype) – Target dtype for packed data.

Returns

Return type

int array.

nutils.numeric.assert_allclose64(actual, data=None, atol=2e-15, rtol=0.002)¶

Assert numerical equivalence with packed data.

Equivalent to numpy.testing.assert_allclose(), with the difference that the desired values are specified as a base64 string representing packed data (see pack() and unpack() for details on packing). The primary use case is embedded regression testing.

The data argument can be left at None to trigger an exception containing the base64 string. The same exception is raised when data is specified but fails the equivalence test, suggesting an update in case failure is expected.

The atol and rtol arguments are used for both unpacking and equivalence testing and cannot be changed independently of the base64 string. Doing so will raise an exception with a suggested update.

Parameters

actual (float array) – The obtained data.
data (str or None) – The desired data in the form of a base64 string.
atol (float) – Absolute tolerance
rtol (float) – Relative tolerance

nutils.numeric.accumulate(data, index, shape)¶

accumulate scattered data in dense array.

Accumulates values from data in an array of shape shape at positions index, equivalent with:

>>> def accumulate(data, index, shape):
...   array = numpy.zeros(shape, data.dtype)
...   for v, *ij in zip(data, *index):
...     array[ij] += v
...   return array

nutils.numeric.asboolean(array, size, ordered=True)¶

convert index array to boolean.

A boolean array is returned as-is after confirming that the length is correct.

>>> asboolean([True, False], size=2)
array([ True, False], dtype=bool)

A strictly increasing integer array is converted to the equivalent boolean array such that asboolean(array, n).nonzero()[0] == array.

>>> asboolean([1,3], size=4)
array([False,  True, False,  True], dtype=bool)

In case the order of integers is not important this must be explicitly specified using the ordered argument.

>>> asboolean([3,1,1], size=4, ordered=False)
array([False,  True, False,  True], dtype=bool)

Parameters

array (int or bool array_like or None) – Integer or boolean index data.
size (int) – Target array length.
ordered (bool) – Assert that integers are strictly increasing.