Utility functions¶
|
Returns the indices that would sort an array. |
|
Sort the given array inplace. |
|
Set the maximum number of threads usable in parallel computing. |
|
Test if the given object is iterable |
|
Decorator: add the decorated function to the specified class. |
|
This function ensure that the given shape will be easily convertible in a c++ callback (ie that it won’t interfere badly in pybind11 overload resolution algorithm) |
|
Linearize the given ndarray according to the given shape. |
|
De-Linearize the given ndarray according to the given shape. |
|
Test if the given object has method member called |
|
Test if a bijection exists between the elements of |
|
Compute the element wise mean of two arrays of angles (radian) handling a modulo \(\pi\) wrapping. |
|
Returns a |
|
Find a common type to a list of numpy arrays. |
|
Find a common type to a list of numpy arrays, cast all arrays that need to be cast to this type and returns the list of arrays (with some of them casted). |
|
Cast the given numpy array to the given dtype and returns the result. |
Return the path to higra include files. |
|
Return the path to higra lib include files. |
|
Return the path to higra lib cmake files. |
-
arg_sort
(array, stable=False)[source]¶ Returns the indices that would sort an array. A parallel algorithm is used if possible.
If
stable
isTrue
, the relative order of equivalent elements is maintained (otherwise the ordering of equivalent elements may be arbitrary or even non deterministic).If the array has 2 dimensions, a lexicographic sort is used.
- Example:
>>> a = np.asarray((5, 2, 1, 4, 9)) >>> hg.arg_sort(a) (2 1 3 0 4)
>>> a = np.asarray(((2, 2, 1, 1, 3), >>> (2, 2, 2, 1, 0))).T >>> hg.arg_sort(a, stable=True) (3 2 0 1 4)
- Parameters:
array – input array (1d or 2d)
stable – if
True
, a stable sort is performed.
- Returns:
A 1d array of indices that would sort the input array
-
sort
(array, stable=False)[source]¶ Sort the given array inplace. A parallel algorithm is used if possible.
If
stable
isTrue
, the relative order of equivalent elements is maintained (otherwise the ordering of equivalent elements may be arbitrary or even non deterministic).- Example:
>>> a = np.asarray((5, 2, 1, 4, 9)) >>> hg.sort(a) >>> a [1 2 4 5 9]
- Parameters:
array – input array (1d or 2d)
stable – if
True
, a stable sort is performed.
- Returns:
nothing
-
set_num_threads
(num_threads: int) → None¶ Set the maximum number of threads usable in parallel computing. If
num_threads
is equal to 0, the maximum number of threads resets to its default value (number of logical cores available on the machine).
-
is_iterable
(obj)[source]¶ Test if the given object is iterable
- Parameters:
obj – an object
- Returns:
True if obj is iterable, False otherwise
-
extend_class
(cls, method_name=None)[source]¶ Decorator: add the decorated function to the specified class. If no name is specified the name of the function is used.
- Example:
>>> class A: >>> pass >>> >>> @extend_class(A, "shiny_method") >>> def hello(self, name): >>> print("Hello", name) >>> >>> a = A() >>> a.shiny_method("foo")
:param cls The class to extend :param method_name The name that the new method will take (If None, it will be determined from the decorated function)
-
normalize_shape
(shape)[source]¶ This function ensure that the given shape will be easily convertible in a c++ callback (ie that it won’t interfere badly in pybind11 overload resolution algorithm)
- Example:
>>> normalize_shape([4, 5]) (4, 5)
- Parameters:
shape – an iterable of integers
- Returns:
the equivalent normalized shape
-
linearize_vertex_weights
(vertex_weights, graph=None, shape=None)[source]¶ Linearize the given ndarray according to the given shape.
If
shape
isNone
, the input array is returned.Else if
shape
is a prefix ofvertex_weights.shape
then thelen(shape)
first dimensions ofvertex_weights
are collapsed (linearized).Else if
vertex_weights.shape[0]
is equal to the product of the elements inshape
then the input array is returned (array was already linearized).Else: an exception is raised.
Note that this function tries its best to guess what should be done but some ambiguity might always exist.
- Examples:
>>> r = hg.linearize_vertex_weights(np.ones((4, 5)), shape=(4, 5)) >>> r.shape (20,)
>>> r = hg.linearize_vertex_weights(np.ones((4, 5, 10, 12)), shape=(4, 5)) >>> r.shape (20, 10, 12)
>>> r = hg.linearize_vertex_weights(np.ones((20,)), shape=(4, 5)) >>> r.shape (20,)
>>> r = hg.linearize_vertex_weights(np.ones((20, 4, 5, 2, 3)), shape=(4, 5)) >>> r.shape (20, 4, 5, 2, 3)
- Raises:
ValueError – if
vertex_weights.shape
andshape
are incompatible.- See:
- Parameters:
vertex_weights – an ndarray representing vertex weights on a square nd-grid
graph – a graph (optional, Concept
CptGridGraph
)shape – a list of integers (optional, deduced from Concept
CptGridGraph
)
- Returns:
maybe reshaped vertex_weights
-
delinearize_vertex_weights
(vertex_weights, graph=None, shape=None)[source]¶ De-Linearize the given ndarray according to the given shape.
If
shape
isNone
, the input array is returned.Else if
shape
is a prefix ofvertex_weights.shape
then the input array is returned.Else if
vertex_weights.shape[0]
is equal to the product of the elements inshape
then the first dimension ofvertex_weights
is expanded (delinearized) into the sequence of dimensions given byshape
Else: an exception is raised.
Note that this function tries its best to guess what should be done but some ambiguity might always exist.
- Examples:
>>> r = hg.delinearize_vertex_weights(np.ones((20,)), shape=(4, 5)) >>> r.shape (4, 5)
>>> r = hg.delinearize_vertex_weights(np.ones((20, 4, 5, 2, 3)), shape=(4, 5)) >>> r.shape (4, 5, 4, 5, 2, 3)
>>> r = hg.delinearize_vertex_weights(np.ones((4, 5)), shape=(4, 5)) >>> r.shape (4, 5)
>>> r = hg.delinearize_vertex_weights(np.ones((4, 5, 10, 12)), shape=(4, 5)) >>> r.shape (4, 5, 10, 12)
- Raises:
ValueError – if
vertex_weights.shape
andshape
are incompatible.- See:
- Parameters:
vertex_weights – an ndarray representing vertex weights on a square nd-grid
graph – a graph (optional, Concept
CptGridGraph
)shape – a list of integers (optional, deduced from Concept
CptGridGraph
)
- Returns:
maybe reshaped vertex_weights
-
has_method
(obj, method_name)[source]¶ Test if the given object has method member called
method_name
.- Parameters:
obj – an object
method_name – a string
- Returns:
True
ifobject.method_name
is a valid callable expression,False
otherwise
-
is_in_bijection
(a, b)[source]¶ Test if a bijection exists between the elements of
a
and the elements ofb
.Given two numpy arrays
a
andb
returnsTrue
ifa
andb
have same sizethere exists a bijective function \(f\) such that, for all \(i\), \(a(i) = f(b(i))\)
Note that input arrays are flattened.
- Parameters:
a – an nd array
b – an nd array
- Returns:
True
if a bijection exists andFalse
otherwise
-
mean_angle_mod_pi
(angles1, angles2)[source]¶ Compute the element wise mean of two arrays of angles (radian) handling a modulo \(\pi\) wrapping.
eg: the modulo \(\pi\) mean angle between 0 and 3.0 is roughly 3.07
- Parameters:
angles1 – must be in \([0; \pi]\)
angles2 – must be in \([0; \pi]\)
- Returns:
average of angles1 and angles2 with correct wrapping in \([0; \pi]\)
-
dtype_info
(dtype)[source]¶ Returns a
numpy.iinfo
object if givendtype
is an integral type, and anumpy.finfo
if givendtype
is a float type.- Raises:
ValueError – if
dtype
is a more complex type.- Parameters:
dtype – a numpy dtype
- Returns:
an info object on given
dtype
-
common_type
(*arrays, safety_level='minimum')[source]¶ Find a common type to a list of numpy arrays.
If safety level is equal to ‘minimum’, then the result type is the smallest that ensures that all values in all arrays can be represented exactly in the given type (except for np.uint64 which is allowed to fit in a np.int64!) In this case the function also guaranties that the result type is integral if all the arrays have integral types.
If safety level is equal to ‘overflow’, the result type ensures a to have a type suitable to contain the result of common operations involving the input arrays (additions, divisions…). This relies on
numpy.common_type
: The return type will always be an inexact (i.e. floating point) scalar type, even if all the arrays are integer arrays. If one of the inputs is an integer array, the minimum precision type that is returned is a 64-bit floating point dtype.All input arrays except
int64
anduint64
can be safely cast to the returneddtype
without loss of information.- Parameters:
arrays – a sequence of numpy arrays
safety_level – either ‘minimum’ or ‘overflow’
- Returns:
a numpy dtype
-
cast_to_common_type
(*arrays, safety_level='minimum')[source]¶ Find a common type to a list of numpy arrays, cast all arrays that need to be cast to this type and returns the list of arrays (with some of them casted).
If safety level is equal to ‘minimum’, then the result type is the smallest that ensures that all values in all arrays can be represented exactly in the given type (except for np.uint64 which is allowed to fit in a np.int64!) In this case the function also guaranties that the result type is integral if all the arrays have integral types.
If safety level is equal to ‘overflow’, the result type ensures a to have a type suitable to contain the result of common operations involving the input arrays (additions, divisions…). This relies on numpy.common_type: The return type will always be an inexact (i.e. floating point) scalar type, even if all the arrays are integer arrays. If one of the inputs is an integer array, the minimum precision type that is returned is a 64-bit floating point dtype.
All input arrays except int64 and uint64 can be safely cast to the returned dtype without loss of information.
- See:
- Parameters:
arrays – a sequence of numpy arrays
safety_level – either ‘minimum’ or ‘overflow’
- Returns:
a list of arrays
-
cast_to_dtype
(array, dtype)[source]¶ Cast the given numpy array to the given dtype and returns the result. If the input array dtype is already equal to the given dtype, the input array is returned.
- Parameters:
array – a numpy array
dtype – a numpy dtype
- Returns:
a numpy array
-
get_include
()[source]¶ Return the path to higra include files. To be used for c++ extension writing.
- Returns: