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

Array of len(v1) = len(v2) with angles between ]-pi,pi]

Example:
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.
Returns:

Array of len(vil) with data from array at vil index vilidx

Example:
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
Returns:array of length n-1 with bin centers
Example:
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
Example:
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
Example:
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
Example:
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
Example:
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
Example:
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
Example:
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
Example:
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.
Returns:

Array of len(vil) with averaged data from array.

Example:
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
Example:
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
Example:
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)
Example:
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
Example:
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
Example:
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.