Utils

Created on Tue Jul 29 09:25:40 2025

@author: Claus Kadelka, Benjamin Coberly

boolforge.utils.bin2dec(binary_vector: list) → int[source]

Convert a binary vector to an integer.

Parameters:

  • binary_vector (list[int]): List containing binary digits (0 or 1).

Returns:

  • int: Integer value converted from the binary vector.

boolforge.utils.dec2bin(integer_value: int, num_bits: int) → list[source]

Convert an integer to a binary vector.

Parameters:

  • integer_value (int): Integer value to be converted.

  • num_bits (int): Number of bits in the binary representation.

Returns:

  • list[int]: List containing binary digits (0 or 1).

boolforge.utils.find_all_indices(arr, el)[source]

Given a list arr, this function returns a list of all the indices i where arr[i]==el. If el not in arr, it raises a ValueError.

boolforge.utils.check_if_empty(my_list: list | ndarray) → bool[source]

Check if the provided list or NumPy array is empty.

Parameters:

  • my_list (list[Variant], np.ndarray[Variant]): The list or array to check.

Returns:

  • bool: True if my_list is empty (or has size 0 for a NumPy array), False otherwise.

boolforge.utils.is_list_or_array_of_ints(x: list | ndarray, required_length: int = None) → bool[source]

Determines if the array-like x contains elements of the ‘integer’ type.

Parameters:

  • x (list | np.ndarray): The array-like to check.

  • required_length (int | None, optional): The exact length x must have to return true. If None, this check is ignored.

Returns:

  • bool: True if x holds elements of type int or np.integer. If required_length is not None, then the length of x must equal required_length as well. Returns false otherwise.

boolforge.utils.is_list_or_array_of_floats(x: list | ndarray, required_length: int = None) → bool[source]

Determines if the array-like x contains elements of the ‘floating point’ type.

Parameters:

  • x (list | np.ndarray): The array-like to check.

  • required_length (int | None, optional): The exact length x must have to return true. If None, this check is ignored.

Returns:

  • bool: True if x holds elements of type float or np.floating. If required_length is not None, then the length of x must equal required_length as well. Returns false otherwise.

boolforge.utils.bool_to_poly(f: list, variables: list | None = None, prefix: str = '') → str[source]

Transform a Boolean function from truth table format to polynomial format in non-reduced DNF.

Parameters:

  • f (list[int]): Boolean function as a vector (list of length 2^n, where n is the number of inputs).

  • variables (list[str] | None, optional): List of indices to use for variable naming. If empty or not matching the required number, defaults to list(range(n)).

  • prefix (str, optional): Prefix for variable names in the polynomial, default ‘’.

Returns:

  • str: A string representing the Boolean function in disjunctive normal form (DNF).

boolforge.utils.f_from_expression(expr: str, max_degree: int = 16) → tuple[source]

Extract a Boolean function from a string expression.

The function converts an input expression into its truth table representation. The expression can include Boolean operators and comparisons, and the order of variables is determined by their first occurrence in the expression.

Parameters:

  • expr (str): A text string containing an evaluable Boolean expression.

Returns:

  • tuple[list[int], list[str]]:

    • f (list[int]): The right-hand side of the Boolean function (truth table) as a list of length 2**n, where n is the number of inputs.

    • var (list[str]): A list of variable names (of length n) in the order they were encountered.

Examples:

>>> f_from_expression('A AND NOT B') #nested canalizing function
([0, 0, 1, 0], ['A', 'B'])

>>> f_from_expression('x1 + x2 + x3 > 1') #threshold function
([0, 0, 0, 1, 0, 1, 1, 1], ['x1', 'x2', 'x3'])

>>> f_from_expression('(x1 + x2 + x3) % 2 == 0') % linear (XOR) function
([1, 0, 0, 1, 0, 1, 1, 0], ['x1', 'x2', 'x3'])
boolforge.utils.flatten(l: list | array) → list[source]

Converts an array of arrays into an array containing the elements of each subarray, effectively reducing the dimension of the array by 1.

Paramters:

  • l (list[list[Variant] | np.array[Variant]] | np.array[list[Variant] | np.array[Variant]]): Array of arrays to reduce the dimension of.

Returns:

  • list[Variant]: Array with its dimensions reduced by 1.

boolforge.utils.get_layer_structure_of_an_NCF_given_its_Hamming_weight(n: int, w: int) → tuple[source]

Compute the canalizing layer structure of a nested canalizing function (NCF) given its Hamming weight.

There exists a bijection between the Hamming weight (with w equivalent to 2^n - w) and the canalizing layer structure of an NCF. The layer structure is represented as [k_1, …, k_r], where each k_i ≥ 1 and, if n > 1, for the last layer k_r ≥ 2.

Parameters:

  • n (int): Number of inputs (variables) of the NCF.

  • w (int): Odd Hamming weight of the NCF, i.e., the number of 1s in the 2^n-vector representation of the function.

Returns:

  • layer_structure_NCF (list[int]): A list [k_1, …, k_r] describing the number of variables in each layer.

References:

  1. Kadelka, C., Kuipers, J., & Laubenbacher, R. (2017). The influence of canalization on the robustness of Boolean networks. Physica D: Nonlinear Phenomena, 353, 39-47.