# DEMutilities. numeric_functions¶

General numeric functions based on numpy that perform vector operations between given arrays. Most arguments in this module are expected to be `numpy.ndarray` instances. These functions are optimized for fast performance and on purpose don’t do any ‘sanity’ checking of in- or output. For example, it is the responsibility of the user that normal unit vectors are actually of length one, and that the shapes of the passed arrays can be correctly broadcasted by numpy.

In order to be able to use this module import it like this:

```import DEMutilities.numeric_functions
#or assign it to a shorter name
import DEMutilities.numeric_functions as num
```

Contents

`DEMutilities.numeric_functions.``aabb`(p)

Returns the minimal point and maximal point of an array’s axis-aligned bounding box (AABB).

Parameters: p – Array with Point-like elements

Returns a np.ndarray array r, with two points:

• `r[0] = (min(x),min(y),min(z))`
• `r[1] = (max(x),max(y),max(z))`

or its equivalent for a different number of dimensions.

`DEMutilities.numeric_functions.``anglebetweenvectors`(v1, v2, n=(0, 1, 0))

Element-wise computation of signed angle between two vectors, given an axis.

Parameters: v1 (`numpy.ndarray`) – Array with multiple elements v2 (`numpy.ndarray`) – Array with multiple elements n – Array with multiple Unit Vector-like elements, or a single unit vector containing the axis over which the computed angle revolves Array of `len(v1) = len(v2)` with angles between `]-pi,pi]`
```v1 = np.array([(1,2,3),(2,3,4)])
v2 = np.array([(5,6,7),(6,7,8)])
n = (0,1,0)
anglebetweenvectors(v1,v2,n)
array([ 0.29849893,  0.1798535 ])
```

Note

`anglebetweenvectors()` will reduce the dimension of the result by one. e.g. in the example above, two arrays with `shape = (2,3)` results in an array with `shape = (2,)`

`DEMutilities.numeric_functions.``array_at_vilidx`(vil, array, vilidx)

Given an array of vertexIndices, and an input array with point data, computes the cell data at a given index of each vertex index list element.

Parameters: vil (`numpy.ndarray`) – Array with vertexIndices, refering to indices in `array`. array – Array with point data. Length of `array` must greater than the maximal index stored in vil. vilidx (int) – An index that refers to the ‘n’-th entry that should be used for each element in `vil`. Array of len(vil) with data from `array` at `vil` index `vilidx`
```p = np.array([(1,2,3),(2,3,4)])
vil = np.array([(0,1)])
array_at_vilidx(vil,p,1)
array([[2, 3, 4]])
array_at_vilidx(vil,p,0)
array([[1, 2, 3]])
```
`DEMutilities.numeric_functions.``bin_centers`(v)

Given an array of bin edges, computes the bin centers. The result is an array of len(v)-1

Parameters: v – array of length n specifying the bin edges array of length n-1 with bin centers
`DEMutilities.numeric_functions.``bin_midpoints`(bins)
`DEMutilities.numeric_functions.``closest_index`(array, value)
`DEMutilities.numeric_functions.``cross`(v1, v2)

Element-wise cross product between two arrays.

Parameters: v1 (`numpy.ndarray`) – Array with multiple elements v2 (`numpy.ndarray`) – Array with multiple elements
```v1 = np.array([(1,2,3),(2,3,4)])
v2 = np.array([(5,6,7),(6,7,8)])
cross( v1, v2 )
array([[-4,  8, -4],[-4,  8, -4]])
```
`DEMutilities.numeric_functions.``dot`(v1, v2)

Element-wise dot product between two arrays.

Parameters: v1 (`numpy.ndarray`) – Array with multiple elements v2 (`numpy.ndarray`) – Array with multiple elements
```v1 = np.array([(1,2,3),(2,3,4)])
v2 = np.array([(5,6,7),(6,7,8)])
dot( v1, v2 )
array([38, 65])
```

Note

`dot()` will reduce the dimension of the result by one. e.g. in the example above, two arrays with `shape = (2,3)` results in an array with `shape = (2,)`

`DEMutilities.numeric_functions.``extract_column`(v, N)

From a vector with multiple columns, extract the Nth column. Identical to: v[:,N]

Parameters: v – array with N or more columns N (int) – index of column to extract
`DEMutilities.numeric_functions.``extract_row`(v, N)

From a vector with multiple rows, extract the Nth row. Identical to: v[N,:]

Parameters: v – array with N or more row N (int) – index of row to extract
`DEMutilities.numeric_functions.``getrandbits`(k) → x. Generates a long int with k random bits.
`DEMutilities.numeric_functions.``indices_to_mask`(N, idxlist)
`DEMutilities.numeric_functions.``is_close_to_absolute`(p, pref, epsilon)

Element-wise check that determines whether an array of float-like elements is close to a given reference value, with a given epsilon.

`DEMutilities.numeric_functions.``is_close_to_relative`(p, pref, epsilon)

Element-wise check that determines whether an array of float-like elements is close, relative to a given reference value, with a given epsilon.

`DEMutilities.numeric_functions.``mag`(v)

Element-wise norm (magnitude) of an array.

Parameters: v (`numpy.ndarray`) – Array with multiple elements
```v = np.array([(1,2,3),(2,3,4)])
norm_sq( v )
array([ 3.74165739,  5.38516481])
```

Note

• norm will reduce the dimension of the result by one. e.g. in the example above, an array with `shape = (2,3)` results in an array with `shape = (2,)`
• `mag()` and `norm()` are identical.
`DEMutilities.numeric_functions.``mask_first_elements`(N, Ntrue)
`DEMutilities.numeric_functions.``mean`(v, emptyval=0, **kwargs)

Returns `numpy.nanmean()` of an array, or emptyval if the array has no elements. The latter is useful for example when binning, since we often want to assign ‘zero’ to a mean quantity in bins with no elements (although ambiguous). **kwargs key word arguments are passed to `numpy.nanmean()`.

`DEMutilities.numeric_functions.``norm`(v)

Element-wise norm (magnitude) of an array.

Parameters: v (`numpy.ndarray`) – Array with multiple elements
```v = np.array([(1,2,3),(2,3,4)])
norm_sq( v )
array([ 3.74165739,  5.38516481])
```

Note

norm will reduce the dimension of the result by one. e.g. in the example above, an array with `shape = (2,3)` results in an array with `shape = (2,)`

`DEMutilities.numeric_functions.``norm_sq`(v)

Element-wise squared norm (magnitude) of arrays.

Parameters: v (`numpy.ndarray`) – Array with multiple elements
```v = np.array([(1,2,3),(2,3,4)])
norm_sq( v )
array([14, 29])
```

Note

norm_sq will reduce the dimension of the result by one. e.g. in the example above, an array with `shape = (2,3)` results in an array with `shape = (2,)`

`DEMutilities.numeric_functions.``normalize`(v)

Element-wise normalization of an array.

Parameters: v (`numpy.ndarray`) – Array with multiple elements
```v = np.array([(1,2,3),(2,3,4)])
normalize( v )
array([[ 0.26726124,  0.53452248,  0.80178373],[ 0.37139068,  0.55708601,  0.74278135]])
```

Note

Zero magnitude elements will result in NaN values of the result. The user is responsible for making sure such cases are handled properly

`DEMutilities.numeric_functions.``point_in_infinte_cylinder`(p, xs, cyl_axis_uv, rs)
`DEMutilities.numeric_functions.``point_in_sphere`(p, xs, rs)

Element-wise check that determines whether an array of points is within an (array of) spheres determined by positions and radii.

Parameters: p (`numpy.ndarray`) – Array with Point-like elements xs (`numpy.ndarray`) – Array with multiple Point-like elements, or a single point that determine the positions of the spheres rs (Either `numpy.ndarray` or float) – Array with multiple Scalar-like elements or a single float that determine the radii of the spheres
```p = np.array([(1,2,3),(2,3,4)])
x = np.array([0,0,0])
r = 5
nf.point_in_sphere(v1, x, r)
array([ True, False], dtype=bool)
```
`DEMutilities.numeric_functions.``point_to_cell`(vil, array)

Given an array of vertexIndices and an input array with point data, computes the cell data as the mean of each n-gon’s corners.

Parameters: vil (`numpy.ndarray`) – Array with vertexIndices, refering to indices in `array`. array – Array with point data. Length of `array` must greater than the maximal index stored in vil. Array of len(vil) with averaged data from `array`.
```p = np.array([(1,2,3),(2,3,4)])
vil = np.array([(0,1)])
point_to_cell(vil,p)
array([[ 1.5,  2.5,  3.5]])
```
`DEMutilities.numeric_functions.``project_to_plane`(p, pplane, nplane)

Element-wise projection of points to a plane defined by point(s) and unit vector(s).

Parameters: p – Array with Point-like elements pplane (`numpy.ndarray`) – Array with multiple Point-like elements, or a single Point-like vector nplane (`numpy.ndarray`) – Array with multiple Unit Vector-like elements, or a single unit vector
```p = np.array([(1,2,3),(2,3,4)])
pplane = np.array([0,0,0])
nplane = np.array([0,1,0])
array([[1, 0, 3],[2, 0, 4]])
```

Note

The user is responsible that the elements of `nplane` are in fact of magnitude 1.

`DEMutilities.numeric_functions.``project_to_unitvector`(v, n)

Element-wise projection of elements in an array on a unit vector, or an array of unit vectors.

Parameters: v (`numpy.ndarray`) – Array with multiple elements n (`numpy.ndarray`) – Array with multiple elements, or a single vector
```v = np.array([(1,2,3),(2,3,4)])
u = np.array([1,0,0])
project_to_unitvector( v, n )
array([[1, 0, 0],[2, 0, 0]])

#or

v = np.array([(1,2,3),(2,3,4)])
u = np.array([(1,0,0),(0,1,0)])
project_to_unitvector( v, n )
array([[1, 0, 0],[0, 3, 0]])
```
`DEMutilities.numeric_functions.``projection_is_within_segment`(p, s1, s2)

Given an array with points, returns a mask that selects the points that - when ortogonally projected - fit within a line segment determined by two points s1 and s2 (or an array thereof).

Parameters: p (`numpy.ndarray`) – Array with Point-like elements refering to coordinates s1 (`numpy.ndarray`) – Array with multiple Point-like elements, or a single point that determine the start of the line segment(s) s2 (`numpy.ndarray`) – Array with multiple Point-like elements, or a single point that determine the end of the line segment(s)
```p = np.array([(1,2,3),(2,3,4)])
s1 = np.array([0,0,0])
s2 = np.array([0,2.5,0])
projection_is_within_segment(p, s1, s2 )
array([ True, False], dtype=bool)
```
`DEMutilities.numeric_functions.``random_mask`(N, p)

Return a randomly selected mask with probability p. In this case p*N values will on average be `True` and (1-p)*N will be `False`.

Note

`random_mask_probability()` computes for each element a random bool with given probability. For a version that guarantees that the fraction of ‘True’ elements will be round( p*N ), see `random_subset()`.

Note

Benchmarking has found that this method is almost twice as fast as `random_subset()`.

`DEMutilities.numeric_functions.``random_subset`(N, Ntrue)

Return a random mask that selects a subset of `N` elements with `Ntrue` values

Note

In contrast to `random_mask()`, `random_subset()` guarantees that `Ntrue` elements will be `True`. When using `random_mask()` with `p=Ntrue/N`, this will be approximately true.

`DEMutilities.numeric_functions.``reject_to_unitvector`(v1, n)

Element-wise rejection of elements in an array with respect to a unit vector, or an array of unit vectors.

Parameters: v (`numpy.ndarray`) – Array with multiple elements n (`numpy.ndarray`) – Array with multiple elements, or a single vector
```v = np.array([(1,2,3),(2,3,4)])
u = np.array([1,0,0])
reject_to_unitvector( v, n )
array([[0, 2, 3],[0, 3, 4]])

#or

v = np.array([(1,2,3),(2,3,4)])
u = np.array([(1,0,0),(0,1,0)])
reject_to_unitvector( v, n )
array([[0, 2, 3],[2, 0, 4]])
```

Note

The user is responsible that the elements of `n` are in fact of magnitude 1.

`DEMutilities.numeric_functions.``repeat_vector_element`(vi, N)

Repeats an element `vi` with dimension M, N times.

Parameters: vi (`numpy.ndarray`) – One-dimesional array with dimension M N (int) – Number of times `vi` should be repeated
```v = np.arrray([1,2,3])
N = 5
repeat_vector_element(v, N)
array( [ [1,2,3], [1,2,3], [1,2,3], [1,2,3], [1,2,3]])
```
`DEMutilities.numeric_functions.``rjust`(array, N, fill_value=nan)
`DEMutilities.numeric_functions.``running_mean`(x, N)

Moving average of array `x` using a window with size N. Left and right edges are averaged using a window with smaller size (resp. cropped on left and right side) the length of return array is identical to `x`

`DEMutilities.numeric_functions.``running_mean2`(x, N)

Moving average of array `x` using a window with size N, computed via convolution. Left and right eged are the zero padded.