These are general utility functions that depend only on the numpy array model. All pyformex modules needing numpy should import everything from this module:
from arraytools import *
Classes defined in module arraytools
Functions defined in module arraytools
Return the sine of an angle in degrees.
For convenience, this can also be used with an angle in radians, by specifying angle_spec=Rad.
>>> print sind(30), sind(pi/6,Rad)
0.5 0.5
Return the cosine of an angle in degrees.
For convenience, this can also be used with an angle in radians, by specifying angle_spec=Rad.
>>> print cosd(60), cosd(pi/3,Rad)
0.5 0.5
Return the tangens of an angle in degrees.
For convenience, this can also be used with an angle in radians, by specifying angle_spec=Rad.
Return the angle whose sine is equal to the argument.
By default, the angle is returned in Degrees. Specifying angle_spec=Rad will return the angle in radians.
>>> print arcsind(0.5), arcsind(1.0,Rad)
30.0 1.57079632679
Return the angle whose cosine is equal to the argument.
By default, the angle is returned in Degrees. Specifying angle_spec=Rad will return the angle in radians.
>>> print arccosd(0.5), arccosd(-1.0,Rad)
60.0 3.14159265359
Return the angle whose tangens is equal to the argument.
By default, the angle is returned in Degrees. Specifying angle_spec=Rad will return the angle in radians.
>>> print arctand(1.0), arctand(-1.0,Rad)
45.0 -0.785398163397
Return the angle whose sine and cosine values are given.
By default, the angle is returned in Degrees. Specifying angle_spec=Rad will return the angle in radians. This returns an angle in the range ]-180,180].
>>> print arctand2(0.0,-1.0), arctand2(-sqrt(0.5),-sqrt(0.5),Rad)
180.0 -2.35619449019
Return the smallest integer e such that 10**e > abs(f).
This returns the number of digits before the decimal point.
>>> print [ niceLogSize(a) for a in [1.3, 35679.23, 0.4, 0.00045676] ]
[1, 5, 0, -3]
Return a nice number close to f.
f is a float number, whose sign is disregarded.
A number close to abs(f) but having only 1 significant digit is returned. By default, the value is above abs(f). Setting below=True returns a value above.
Example:
>>> numbers = [ 0.0837, 0.837, 8.37, 83.7, 93.7]
>>> [ str(niceNumber(f)) for f in numbers ]
['0.09', '0.9', '9.0', '90.0', '100.0']
>>> [ str(niceNumber(f,below=True)) for f in numbers ]
['0.08', '0.8', '8.0', '80.0', '90.0']
Return the dot product of vectors of A and B in the direction of axis.
This multiplies the elements of the arrays A and B, and the sums the result in the direction of the specified axis. Default is the last axis. Thus, if A and B are sets of vectors in their last array direction, the result is the dot product of vectors of A with vectors of B. A and B should be broadcast compatible.
>>> A = array( [[1.0, 1.0], [1.0,-1.0], [0.0, 5.0]] )
>>> B = array( [[5.0, 3.0], [2.0, 3.0], [1.33,2.0]] )
>>> print dotpr(A,B)
[ 8. -1. 10.]
Returns the length of the vectors of A in the direction of axis.
The components of the vectors are stored along the specified array axis (default axis is the last).
Normalize the vectors of A in the direction of axis.
The components of the vectors are stored along the specified array axis (default axis is the last).
Return the (signed) length of the projection of vector of A on B.
The components of the vectors are stored along the specified array axis (default axis is the last).
Return the component of vector of A that is orthogonal to B.
The components of the vectors are stored along the specified array axis (default axis is the last).
Return thr n-norm of the vector v.
Default is the quadratic norm (vector length). n == 1 returns the sum. n<=0 returns the max absolute value.
Compute the value of a polynom using Horner’s rule.
Parameters:
Returns float(nu,nd), nd-dimensional values of the polynom.
>>> print horner([[1.,1.,1.],[1.,2.,3.]],[0.5,1.0])
[[ 1.5 2. 2.5]
[ 2. 3. 4. ]]
Solve many systems of linear equations.
Parameters:
Returns: a float array x with same shape as b, where x[:,i,j] solves the system of linear equations A[:,:,j].x[:,i,j] = b[:,i,j].
For ndof in [1,2,3], all solutions are by default computed directly and simultaneously. If direct=False is specified, a general linear equation solver is called for each system of equations. This is also the method used if ndof>4.
Return true if point p is inside bbox defined by points mi and ma
Returns an array flagging the elements close to target.
values is a float array, target is a float value. values and target should be broadcastable to the same shape.
The return value is a boolean array with shape of values flagging
where the values are close to target.
Two values a and b are considered close if
Create a 3D vector.
v is some data compatible with a (3)-shaped float array. Returns v as such an array.
Return a unit vector in the direction of v.
Return a rotation matrix over angle, optionally around axis.
The angle is specified in degrees, unless angle_spec=Rad is specified. If axis==None (default), a 2x2 rotation matrix is returned. Else, axis should specifying the rotation axis in a 3D world. It is either one of 0,1,2, specifying a global axis, or a vector with 3 components specifying an axis through the origin. In either case a 3x3 rotation matrix is returned. Note that:
but the latter functions calls are more efficient. The result is returned as an array.
Create a rotation matrix defined by 3 points in space.
x is an array of 3 points. After applying the resulting rotation matrix to the global axes, the 0 axis becomes // to the vecors x0-x1, the 1 axis lies in the plane x0,x1,x2 and is orthogonal to x0-x1, and the 3 axis is orthogonal to the plane x0,x1,x2.
Find the transformation matrix from points x0 to x1.
x and y are each arrays of 3 non-colinear points. The return value is a tuple of a translation vector and a rotation matrix. The returned translation trl and rotationmatrix rot transform the points x thus that:
The rotation is to be applied first and should be around the first point x0. The full transformation of a Coords object is thus obtained by:
(coords-x0)*rot+trl+x0=coords*rot+(trl+x0-x0*rot)
Create a rotation matrix that rotates axis 0 to the given vector.
u is a vector representing the Return either a 3x3(default) or 4x4(if n==4) rotation matrix.
Return rotation angles from rotation matrix mat.
This returns the three angles around the global axes 0, 1 and 2. The angles are returned in degrees, unless angle_spec=Rad.
Return a rotation matrix for rotating vector vec1 to vec2.
If upvec is specified, the rotation matrix will be such that the plane of vec2 and the rotated upvec will be parallel to the original upvec.
This function is like arraytools.rotMatrix(), but allows the specification of vec1. The returned matrix should be used in postmultiplication to the Coords.
Increase the length of a single array axis.
The specified axis of the array a is increased with a value add and the new elements all get the value fill.
Parameters:
Returns an array with same dimension and type as a, but with a length along axis equal to a.shape[axis]+add. The new elements all have the value fill.
Example:
>>> growAxis([[1,2,3],[4,5,6]],2)
array([[1, 2, 3, 0, 0],
[4, 5, 6, 0, 0]])
Reorder the planes of an array along the specified axis.
The elements of the array are reordered along the specified axis according to the specified order.
Parameters:
a: array_like
order: specifies how to reorder the elements. It is either one of the special string values defined below, or else it is an index holding a permutation of arange(self.nelems(). Each value specifies the index of the old element that should be placed at its position. Thus, the order values are the old index numbers at the position of the new index number.
order can also take one of the following predefined values, resulting in the corresponding renumbering scheme being generated:
Returns an array with the same elements of self, where only the order along the specified axis has been changed.
Example:
>>> reorderAxis([[1,2,3],[4,5,6]],[2,0,1])
array([[3, 1, 2],
[6, 4, 5]])
Reverse the elements along a computed axis.
Example:
>>> reverseAxis([[1,2,3],[4,5,6]],0)
array([[4, 5, 6],
[1, 2, 3]])
Note that if the axis is known in advance, it may be more efficient to use an indexing operation:
>>> A = array([[1,2,3],[4,5,6]])
>>> print A[:,::-1]
[[3 2 1]
[6 5 4]]
Add an additional axis with length 1 to an array.
The new axis is inserted before the specified one. Default is to add it at the front.
Stack a list of arrays along a new axis.
al is a list of arrays all of the same shape. The return value is a new array with one extra axis, along which the input arrays are stacked. The position of the new axis can be specified, and is the first axis by default.
Smart array concatenation ignoring empty arrays
Check that an array a has the correct shape and type.
The input a is anything that can be converted into a numpy array. Either shape and/or kind can be specified. and will then be checked. The dimensions where shape contains a -1 value are not checked. The number of dimensions should match. If kind does not match, but the value is included in allow, conversion to the requested type is attempted.
Returns the array if valid; else, an error is raised.
Check that an array a has the correct size and type.
Either size and or kind can be specified. If kind does not match, but is included in allow, conversion to the requested type is attempted. Returns the array if valid. Else, an error is raised.
Check that an array has the correct dimensionality.
Returns asarray(a) if ndim < 0 or a.ndim == ndim Else, an error is raised.
Check that an array contains a set of unique integers in a given range.
This functions tests that all integer numbers in the array are within the range math:nmin <= i < nmax
Parameters:
Default range is [0,unlimited].
If the numbers are no unique or one of the limits is passed, an error is raised. Else, the sorted list of unique values is returned.
Read an array from an open file.
This uses numpy.fromfile() to read an array with known shape and data type from an open file. The sep parameter can be specified as in fromfile.
Write an array to an open file.
This uses numpy.tofile() to write an array to an open file. The sep parameter can be specified as in tofile.
Solve a cubiq equation using a direct method.
a,b,c,d are the (floating point) coefficients of a third degree polynomial equation:
a*x**3+b*x**2+c*x+d=0
This function computes the three roots (real and complex) of this equation and returns full information about their kind, sorting order, occurrence of double roots. It uses scaling of the variables to enhance the accuracy.
The return value is a tuple (r1,r2,r3,kind), where r1,r2 and r3 are three float values and kind is an integer specifying the kind of roots.
Depending on the value of kind, the roots are defined as follows:
kind | roots |
---|---|
0 | three real roots r1 < r2 < r3 |
1 | three real roots r1 < r2 = r3 |
2 | three real roots r1 = r2 < r3 |
3 | three real roots r1 = r2 = r3 |
4 | one real root r1 and two complex conjugate roots with real part r2 and imaginary part r3; the complex roots are thus: r2+i*r3 en r2-i*r3, where i=sqrt(-1). |
If the coefficient a==0, a ValueError is raised.
Example:
>>> cubicEquation(1.,-3.,3.,-1.)
([1.0, 1.0, 1.0], 3)
Find the unique elements of an array.
This works like numpy’s unique, but uses a stable sorting algorithm. The returned index may therefore hold other entries for multiply occurring values. In such case, uniqueOrdered returns the first occurrence in the flattened array. The unique elements and the inverse index are always the same as those returned by numpy’s unique.
Parameters:
Returns:
Example:
>>> a = array([2,3,4,5,6,7,8,1,2,3,4,5,6,7,8,7,8])
>>> uniq,ind,inv = unique(a,True,True)
>>> print uniq
[1 2 3 4 5 6 7 8]
>>> print ind
[7 0 1 2 3 4 5 6]
>>> print inv
[1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 6 7]
>>> uniq,ind,inv = uniqueOrdered(a,True,True)
>>> print uniq
[1 2 3 4 5 6 7 8]
>>> print ind
[7 0 1 2 3 4 5 6]
>>> print inv
[1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 6 7]
Notice the difference in the fourth element of the ind array.
Renumber an index sequentially.
Given a one-dimensional integer array with only non-negative values, and nval being the number of different values in it, and you want to replace its elements with values in the range 0..nval, such that identical numbers are always replaced with the same number and the new values at their first occurrence form an increasing sequence 0..nval. This function will give you the old numbers corresponding with each position 0..nval.
Parameters:
Returns:
A 1-D integer array with length equal to nval, where nval is the number of different values in index, and holding the original values corresponding to the new value 0..nval.
Remark:
Use inverseUniqueIndex() to find the inverse mapping needed to replace the values in the index by the new ones.
Example:
>>> renumberIndex([0,5,2,2,6,0])
array([0, 5, 2, 6])
>>> inverseUniqueIndex(renumberIndex([0,5,2,2,6,0]))[[0,5,2,2,6,0]]
array([0, 1, 2, 2, 3, 0])
Return the complement of an index in a range(0,n).
The complement is the list of numbers from the range(0,n) that are not included in the index.
Parameters:
Returns:
If index is integer: a 1-D integer array with the numbers from range(0,n) that are not included in index. If index is boolean, the negated index padded to or cut at length n.
Example:
>>> print complement([0,5,2,6])
[1 3 4]
>>> print complement([0,5,2,6],10)
[1 3 4 7 8 9]
>>> print complement([False,True,True,True],6)
[ True False False False True True]
Inverse an index.
Given a 1-D integer array with unique non-negative values, and max being the highest value in it, this function returns the position in the array of the values 0..max. Values not occurring in input index get a value -1 in the inverse index.
Parameters:
Returns:
A 1-D integer array with length max+1, with the positions in index of the values 0..max, or -1 if the value does not occur in index.
Remark:
The inverse index translates the unique index numbers in a sequential index, so that inverseUniqueIndex(index)[index] == arange(1+index.max()).
Example:
>>> inverseUniqueIndex([0,5,2,6])
array([ 0, -1, 2, -1, -1, 1, 3])
>>> inverseUniqueIndex([0,5,2,6])[[0,5,2,6]]
array([0, 1, 2, 3])
Sort subsets of an integer array a.
a is a 1-D integer array. Subsets of the array are the collections of equal values. w is a float array with same size of a, specifying a weight for each of the array elements in a. If no weight is specified, all elements have the same weight.
The subsets of a are sorted in order of decreasing total weight of the subsets (or number of elements if weight is None).
The return value is an integer array of the same size of a, specifying for each element the index of its subset in the sorted list of subsets.
Example:
>>> sortSubsets([0,1,2,3,1,2,3,2,3,3])
array([3, 2, 1, 0, 2, 1, 0, 1, 0, 0])
>>> sortSubsets([0,1,2,3,1,2,3,2,3,3],w=[9,8,7,6,5,4,3,2,1,0])
array([3, 1, 0, 2, 1, 0, 2, 0, 2, 2])
Sort an array on all its columns, from left to right.
The rows of a 2-dimensional array are sorted, first on the first column, then on the second to resolve ties, etc..
Parameters:
Example:
>>> sortByColumns([[1,2],[2,3],[3,2],[1,3],[2,3]])
array([0, 3, 1, 4, 2])
Return (the indices of) the unique rows of a 2-D array.
Parameters:
Returns:
Example:
>>> uniqueRows([[1,2],[2,3],[3,2],[1,3],[2,3]])
(array([0, 3, 1, 2]), array([0, 2, 3, 1, 2]))
>>> uniqueRows([[1,2],[2,3],[3,2],[1,3],[2,3]],permutations=True)
(array([0, 3, 1]), array([0, 2, 2, 1, 2]))
Return the index of the item nearest to target.
Parameters:
Returns the position of the item in values that is nearest to target.
Example:
>>> argNearestValue([0.1,0.5,0.9],0.7)
1
Return the item nearest to target.
values: a list of float values
target: a single value
Returns the item in values values that is nearest to target.
Return an inverse index.
An index is an array pointing at other items by their position. The inverse index is a collection of the reverse pointers. Negative values in the input index are disregarded.
Parameters:
Returns:
An (mr,mc) shaped integer array where:
- mr will be equal to the highest positive value in index, +1.
- mc will be equal to the highest row-multiplicity of any number in index.
Row i of the inverse index contains all the row numbers of index that contain the number i. Because the number of rows containing the number i is usually not a constant, the resulting array will have a number of columns mc corresponding to the highest row-occurrence of any single number. Shorter rows are padded with -1 values to flag non-existing entries.
Example:
>>> inverseIndex([[0,1],[0,2],[1,2],[0,3]])
array([[ 0, 1, 3],
[-1, 0, 2],
[-1, 1, 2],
[-1, -1, 3]])
Find position of values in target.
This function finds the position in the array target of the elements from the array values.
Parameters:
Returns:
An index array with the same size as values. For each number in values, the index contains the position of that value in the flattened target, or -1 if that number does not occur in target. If an element from values occurs more than once in target, it is currently undefined which of those positions is returned.
Remark that after m = matchIndex(target,values) the equality target[m] == values holds in all the non-negative positions of m.
Example:
>>> A = array([1,3,4,5,7,8,9])
>>> B = array([0,6,7,1,2])
>>> matchIndex(A,B)
array([-1, -1, 4, 0, -1])
Compute the group minimum
Computes the minimum value per group of a set of values tagged with a group number.
Parameters:
Returns:
After return, the minimum values corresponding to the groups in ugid are given by val[minpos].
>>> val = array([ 0.0, 1.0, 2.0, 3.0, 4.0, -5.0 ])
>>> gid = array([ 2, 1, 1, 6, 6, 1 ])
>>> print groupArgmin(val,gid)
(array([1, 2, 6]), array([5, 0, 3]))
Return the lengths of a set of vectors.
vec is an (n,3) shaped array holding a collection of vectors. The result is an (n,) shaped array with the length of each vector.
Normalize a set of vectors.
vec is a (n,3) shaped arrays holding a collection of vectors. The result is a tuple of two arrays:
Compute area of and normals on parallellograms formed by vec1 and vec2.
vec1 and vec2 are (n,3) shaped arrays holding collections of vectors. As a convenience, single vectors may also be specified with shape (3,), and will be converted to (1,3).
The result is a tuple of two arrays:
These are calculated from the cross product of vec1 and vec2, which indeed gives area * normal.
Note that where two vectors are parallel, an area zero results and an axis with components NaN.
Compute area of the parallellogram formed by a vector pair vec1,vec2.
vec1 and vec2 are (n,3) shaped arrays holding collections of vectors. The result is an (n) shaped array with the area of the parallellograms formed by each pair of vectors (vec1,vec2).
Compute vectors normal to vec1 and vec2.
vec1 and vec2 are (n,3) shaped arrays holding collections of vectors. The result is an (n,3) shaped array of unit length vectors normal to each couple (edg1,edg2).
Compute triple product vec1 . (vec2 x vec3).
vec1, vec2, vec3 are (n,3) shaped arrays holding collections of vectors. The result is a (n,) shaped array with the triple product of each set of corresponding vectors from vec1,vec2,vec3. This is also the square of the volume of the parallellepid formex by the 3 vectors. If vec1 is a unit normal, the result is also the area of the parallellogram (vec2,vec3) projected in the direction vec1.
Return the cosinus of the angle between the vectors v1 and v2.
vec1 and vec2 are (n,3) shaped arrays holding collections of vectors. The result is an (n) shaped array with the cosinus of the angle between each pair of vectors (vec1,vec2).
Return the angle (in radians) between the vectors v1 and v2.
vec1 and vec2 are (n,3) shaped arrays holding collections of vectors. The result is an (n) shaped array with the angle between each pair of vectors (vec1,vec2).
Return the multiplicity of the numbers in a
a is a 1-D integer array.
Returns a tuple of:
Example:
>>> multiplicity([0,3,5,1,4,1,0,7,1])
(array([2, 3, 1, 1, 1, 1]), array([0, 1, 3, 4, 5, 7]))
Compute the histogram of a set of data.
This function is like numpy’s histogram function, but also returns the bin index for each individual entry in the data set.
Parameters:
Returns:
Example:
>>> hist,ind,xbins = histogram2([1,2,3,4,2,3,1],[1,2,3,4,5])
>>> print hist
[2 2 2 1]
>>> for i in ind: print i
[0 6]
[1 4]
[2 5]
[3]
>>> print xbins
[1 2 3 4 5]
Create a moving view along the first axis of an array
Parameters:
axis of length w.
Using swapaxes(0,axis) moving views over any axis can be created.
Examples:
>>> x=arange(10).reshape((5,2))
>>> print x
[[0 1]
[2 3]
[4 5]
[6 7]
[8 9]]
>>> print movingView(x, 3)
[[[0 1]
[2 3]
[4 5]]
<BLANKLINE>
[[2 3]
[4 5]
[6 7]]
<BLANKLINE>
[[4 5]
[6 7]
[8 9]]]
Calculate rolling sum of first axis:
>>> print movingView(x, 3).sum(axis=0)
[[ 6 9]
[12 15]
[18 21]]
Compute the moving average along the first axis of an array.
Parameters:
Returns:
An array with the moving average over n data sets along the first axis of a. The array has the same shape as a, except possibly for the length of the first axis. If neither m0 nor m1 are set, the first axis will have a length of a.shape[0] - (n-1). If both m0 and m1 are give, the first axis will have a length of a.shape[0] - (n-1) + m0 + m1. If either m0 or m1 are set and the other not, the missing value m0 or m1 will be computed thus that the return array has a first axis with length a.shape[0].
Examples:
>>> x=arange(10).reshape((5,2))
>>> print movingAverage(x,3)
[[ 2. 3.]
[ 4. 5.]
[ 6. 7.]]
>>> print movingAverage(x,3,2)
[[ 0. 1. ]
[ 0.66666667 1.66666667]
[ 2. 3. ]
[ 4. 5. ]
[ 6. 7. ]]
Create an array with random values between min and max
Divide a unit interval in equal parts.
This function is intended to be used by interpolation functions that accept an input as either an int or a list of floats.
Parameters:
Returns: If div is a an integer, returns the floating point values dividing the unit interval in div equal parts. If div is a list, just returns div as a 1D array.
Create a set of uniformly distributed parameter values in a range.
Parameters:
Returns:
A float array with n+1 equidistant values in the range umin..umax. For n > 0, both of the endpoints are included. For n=0, a single value at the center of the interval will be returned. For n<0, an empty array is returned.
Example:
>>> uniformParamValues(4).tolist()
[0.0, 0.25, 0.5, 0.75, 1.0]
>>> uniformParamValues(0).tolist()
[0.5]
>>> uniformParamValues(-1).tolist()
[]
>>> uniformParamValues(2,1.5,2.5).tolist()
[1.5, 2.0, 2.5]