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)

boolforge.utils.filter_kwargs(function, kwargs, exclude=())[source]

Filter a dictionary of keyword arguments for a given function.

Parameters

functioncallable: Function whose signature should be inspected.
kwargsdict: Keyword arguments to filter.
excludeiterable of str, optional: Keyword names to exclude even if accepted by function.

Returns

dict: Dictionary containing only keyword arguments accepted by function and not listed in exclude.

Notes

If function accepts **kwargs, the input dictionary is returned unchanged.
Unused keyword arguments generate a warning or raise a TypeError depending on the value of STRICT.

boolforge.utils.allowed_keywords(function)[source]

Return the keyword arguments accepted by a function.

Parameters

functioncallable: Function whose signature should be inspected.

Returns

set of str: Names of all parameters except *args (variable positional arguments). Returns an empty set if the function signature cannot be determined.

boolforge.utils.get_minimal_trap_space(states: Sequence[int], N: int) → ndarray[source]

Compute the minimal trap space containing a collection of states.

Nodes that take the same value in every state are assigned that value (0 or 1). Nodes that vary across the states are assigned -1, indicating a free variable.

Parameters

statessequence of int: States encoded as integers.
Nint: Number of nodes in the network.

Returns

numpy.ndarray: Length-N array containing 0 (fixed OFF), 1 (fixed ON), or -1 (free).

boolforge.utils.get_shannon_entropy(probabilities: Sequence[float]) → float[source]

Compute the Shannon entropy of a probability distribution.

Parameters

probabilitiesSequence[float]: Nonnegative weights representing a probability distribution. The values are normalized internally if they do not sum to one.

Returns

float

Shannon entropy

H = -sum(p_i * log(p_i)),

where p_i are the normalized probabilities.

boolforge.utils.get_number_of_varying_nodes(states: Sequence[int])[source]

Return the number of nodes that vary across a collection of states.

A node is considered varying if it takes different values in at least two states.

Parameters

statessequence of int: Binary vectors (states) encoded as integers.

Returns

int: Number of varying nodes.