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

>>> import boolforge
>>> boolforge.bin2dec([1, 0, 1])
5
>>> boolforge.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.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)