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