# 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.full(shape, fill_value, dtype)

read-only equivalent to `numpy.full()`

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, dtype=None)

Multi-dimensional meshgrid generalisation.

Meshgrid stacks `n` arbitry-dimensional arrays into an array that is one dimension higher than all dimensions combined, such that `retval[i]` equals `args[i]` broadcasted to consecutive dimension slices. For two vector arguments this is almost equal to `numpy.meshgrid()`, with the main difference that dimensions are not swapped in the return values. The other difference is that the return value is a single array, but since the stacked axis is the first dimension the result can always be tuple unpacked.

Parameters
Returns

Return type

`numpy.ndarray`

nutils.numeric.simplex_grid(shape, spacing)

Multi-dimensional generator for equilateral simplex grids.

Simplex_grid generates a point cloud within an n-dimensional orthotope, which ranges from zero to a specified shape. The point coordinates are spaced in such a way that the nearest neighbours are at distance spacing, thus forming vertices of regular simplices. The returned array is two-dimensional, with the first axis being the spatial dimension (matching shape) and the second a stacking of the generated points.

Parameters
Returns

Return type

`numpy.ndarray`

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
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
Returns

Return type

`int` array.

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() == 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
nutils.numeric.invmap(indices, length, missing=- 1)

Create inverse index array.

Create the index array `inverse` with the given `length` such that `inverse[indices[i]] == i` and `inverse[j] == missing` for all `j` not in `indices`. It is an error to pass an `indices` array with repeated indices, in which case the result is undefined.

```>>> m = invmap([3,1], length=5)
>>> m
0
>>> m
1
```
Parameters
Returns

Return type

`numpy.ndarray`

nutils.numeric.levicivita(n, dtype=<class 'float'>)

n-dimensional Levi-Civita symbol.