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. 

DeLinearize 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 ndgrid
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]¶ DeLinearize 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 ndgrid
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 64bit 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 64bit 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: