Utils

Utility functions used throughout BoolForge.

The utils module includes low-level operations for binary and decimal conversions, truth table manipulations, and combinatorial helper functions. These utilities are used internally by BooleanFunction and BooleanNetwork classes to enable efficient representation and analysis of Boolean functions and networks.

Notes

Most functions in this module are intended for internal use and are not part of the stable public API.

Examples

>>> from boolforge import utils
>>> utils.bin2dec([1, 0, 1])
5
>>> utils.dec2bin(5, 3)
array([1, 0, 1])
boolforge.utils.bin2dec(binary_vector: list[int]) → int[source]

Convert a binary vector to an integer.

Parameters

binary_vectorlist of int

Binary digits (0 or 1), ordered from most significant bit to least significant bit.

Returns

int

Integer represented by the binary vector.

Notes

No validation is performed to ensure that entries of binary_vector are binary. Nonzero values are treated as 1 under bitwise conversion.

Examples

>>> bin2dec([1, 0, 1])
5
>>> bin2dec([0, 0, 1, 1])
3
boolforge.utils.dec2bin(integer_value: int, num_bits: int) → list[int][source]

Convert a nonnegative integer to a binary vector.

Parameters

integer_valueint

Nonnegative integer to convert.

num_bitsint

Length of the binary representation.

Returns

list of int

Binary digits (0 or 1), ordered from most significant bit to least significant bit.

Notes

  • If integer_value requires more than num_bits bits, the most significant bits are truncated.

  • No validation is performed for negative inputs.

Examples

>>> dec2bin(5, 3)
[1, 0, 1]
>>> dec2bin(3, 5)
[0, 0, 0, 1, 1]
boolforge.utils.bool_to_poly(f: list, variables: list[str] | None = None, prefix: str = '') → str[source]

Convert a Boolean function from truth-table form to disjunctive normal form.

The returned expression is a non-reduced disjunctive normal form (DNF), expressed as a sum of monomials corresponding to truth-table entries where the function evaluates to 1.

Parameters

flist

Boolean function values ordered according to the standard truth-table convention. The length of f must be 2**n for some integer n.

variableslist of str or None, optional

Variable names to use in the expression. If None or if the length does not match the required number of variables, default names ['x0', 'x1', ..., 'x{n-1}'] are used.

prefixstr, optional

Prefix for automatically generated variable names. Ignored if variables is provided with the correct length.

Returns

str

Boolean expression in non-reduced disjunctive normal form. Returns '0' if the function is identically zero.

Notes

  • Variables are ordered from most significant bit to least significant bit.

  • Each monomial corresponds to a single truth-table row where f == 1.

  • No simplification or reduction of the DNF is performed.

Examples

>>> bool_to_poly([0, 1, 1, 0])
'(1 - x0) * x1 + x0 * (1 - x1)'
boolforge.utils.f_from_expression(expr: str, max_degree: int = 16) → tuple[ndarray, ndarray][source]

Construct a Boolean function from a string expression.

The expression is evaluated symbolically over all Boolean input combinations to produce the truth table of the corresponding Boolean function. Variables are detected automatically based on their first occurrence in the expression.

Parameters

exprstr

Boolean expression to evaluate. The expression may contain logical operators (AND, OR, NOT or their lowercase equivalents), arithmetic operators, and comparisons.

max_degreeint, optional

Maximum number of variables allowed. If the number of detected variables exceeds max_degree, an empty truth table is returned.

Returns

fnp.ndarray

Boolean function values as an array of shape (2**n,) with entries in {0, 1}, where n is the number of detected variables.

variablesnp.ndarray

Variable names in the order they were first encountered in the expression.

Notes

  • Variables are ordered by first occurrence in expr.

  • Truth-table rows follow the standard lexicographic ordering with the most significant bit first.

  • The expression is evaluated using eval with restricted builtins.

  • No syntactic or semantic validation of expr is performed beyond basic parsing.

Examples

>>> f_from_expression('A AND NOT B')
(array([0, 0, 1, 0], dtype=uint8), array(['A', 'B'], dtype='<U1'))

>>> f_from_expression('x1 + x2 + x3 > 1')
(array([0, 0, 0, 1, 0, 1, 1, 1], dtype=uint8),
 array(['x1', 'x2', 'x3'], dtype='<U2'))

>>> f_from_expression('(x1 + x2 + x3) % 2 == 0')
(array([1, 0, 0, 1, 0, 1, 1, 0], dtype=uint8),
 array(['x1', 'x2', 'x3'], dtype='<U2'))
boolforge.utils.hamming_weight_to_ncf_layer_structure(n: int, w: int) → list[int][source]

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

For nested canalizing functions, there is a bijection between the (odd) Hamming weight w and the canalizing layer structure, with w and 2**n - w corresponding to the same structure.

Parameters

nint

Number of input variables of the NCF.

wint

Odd Hamming weight of the NCF.

Returns

list of int

Canalizing layer structure [k_1, ..., k_r].

Raises

TypeError

If w is not an integer.

ValueError

If w is outside [1, 2**n - 1] or if w is even.

Notes

  • All nested canalizing functions have odd Hamming weight.

  • The binary expansion of w (with n bits) determines the layer structure.

References

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

boolforge.utils.get_left_side_of_truth_table(N: int) → ndarray[source]

Return the left-hand side of a Boolean truth table.

The left-hand side is the binary representation of all 2**N input combinations for N Boolean variables, ordered lexicographically from 0 to 2**N - 1.

Parameters

Nint

Number of Boolean variables.

Returns

np.ndarray

Array of shape (2**N, N) with entries in {0, 1}. Columns are ordered from most significant bit to least significant bit.

Notes

  • The result is cached by N to avoid recomputation.

  • Row i corresponds to the binary expansion of integer i.

  • The most significant bit appears in column 0.

Examples

>>> get_left_side_of_truth_table(2)
array([[0, 0],
       [0, 1],
       [1, 0],
       [1, 1]], dtype=uint8)