# Utility functions¶

 arg_sort(array[, stable]) Returns the indices that would sort an array. sort(array[, stable]) Sort the given array inplace. set_num_threads(num_threads) Set the maximum number of threads usable in parallel computing. Test if the given object is iterable extend_class(cls[, method_name]) Decorator: add the decorated function to the specified class. normalize_shape(shape) 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_vertex_weights(vertex_weights[, …]) Linearize the given ndarray according to the given shape. delinearize_vertex_weights(vertex_weights[, …]) De-Linearize the given ndarray according to the given shape. has_method(obj, method_name) Test if the given object has method member called method_name. Test if a bijection exists between the elements of a and the elements of b. mean_angle_mod_pi(angles1, angles2) Compute the element wise mean of two arrays of angles (radian) handling a modulo $$\pi$$ wrapping. dtype_info(dtype) Returns a numpy.iinfo object if given dtype is an integral type, and a numpy.finfo if given dtype is a float type. common_type(*arrays[, safety_level]) Find a common type to a list of numpy arrays. cast_to_common_type(*arrays[, safety_level]) 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_to_dtype(array, dtype) 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 is True, 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 is True, 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 is None, the input array is returned.

Else if shape is a prefix of vertex_weights.shape then the len(shape) first dimensions of vertex_weights are collapsed (linearized).

Else if vertex_weights.shape[0] is equal to the product of the elements in shape 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 and shape are incompatible.

See

delinearize_vertex_weights()

Parameters
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 is None, the input array is returned.

Else if shape is a prefix of vertex_weights.shape then the input array is returned.

Else if vertex_weights.shape[0] is equal to the product of the elements in shape then the first dimension of vertex_weights is expanded (delinearized) into the sequence of dimensions given by shape

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 and shape are incompatible.

See

linearize_vertex_weights()

Parameters
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 if object.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 of b.

Given two numpy arrays a and b returns True if

• a and b have same size

• there 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 and False 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 given dtype is an integral type, and a numpy.finfo if given dtype 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 and uint64 can be safely cast to the returned dtype 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

common_type()

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

get_lib_include()[source]

Return the path to higra lib include files. To be used for c++ extension writing.

Returns

get_lib_cmake()[source]

Return the path to higra lib cmake files. To be used for c++ extension writing.

Returns